Receive webhooks
Get told when a code must stop working, and verify that the call came from ENDVR.
ENDVR sends events to one HTTPS endpoint of yours. They follow the Standard Webhooks specification.
Events
| Event | When | What to do |
|---|---|---|
code.deactivate | A code must stop working: the brand removed the associate, or the associate left a targeted store. | Disable or delete the code in your store. |
pro_deal.ended | The Pro Deal ended. | Disable its codes that were not used. |
Every event has the same envelope:
{
"type": "code.deactivate",
"timestamp": "2026-11-17T15:20:11Z",
"data": {
"proDealId": "6730f1c2a9d4e5b6c7d8e9f0",
"code": "PRO-7KQ2-XM4D",
"reason": "associate_left_store"
}
}Set the endpoint
curl -X PUT https://api.endvr.io/v1/webhooks \
-H "Authorization: Bearer $ENDVR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://shop.example.com/endvr/webhooks", "events": ["code.deactivate", "pro_deal.ended"] }'The first answer carries the signing secret (whsec_…). Store it with your other secrets: it is not shown again.
Verify every request
Each request carries three headers:
| Header | Content |
|---|---|
webhook-id | The event id, the same on every retry. |
webhook-timestamp | Seconds since the Unix epoch when this attempt was signed. |
webhook-signature | One or more v1,<signature> values, separated by spaces. |
The signature is the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with your secret
after removing the whsec_ prefix and base64-decoding the rest. To verify:
- Reject the request if
webhook-timestampis more than 5 minutes from your clock. - Compute the signature over the raw body, before any JSON parsing.
- Accept the request if any
v1value inwebhook-signaturematches, using a constant-time comparison.
import crypto from "node:crypto";
export function verifyEndvrWebhook(secret, headers, rawBody) {
const id = headers["webhook-id"];
const timestamp = headers["webhook-timestamp"];
const signatures = headers["webhook-signature"] ?? "";
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
throw new Error("Webhook timestamp is too old or in the future");
}
const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
const expected = crypto.createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest("base64");
const valid = signatures.split(" ").some((entry) => {
const [version, signature] = entry.split(",");
return (
version === "v1" &&
signature?.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
);
});
if (!valid) throw new Error("Invalid webhook signature");
}The Standard Webhooks libraries do the same in many languages.
Respond and process
- Answer
2xxas soon as the event is stored, then do the work in the background. - Any other answer, or no answer, is retried with exponential backoff for 24 hours.
- The same event can arrive more than once: use
webhook-idto skip the ones you already handled. - Events can arrive out of order. Deactivating a code twice must be harmless.
Test it
Send a signed sample of any event to your endpoint:
curl -X POST https://api.endvr.io/v1/webhooks/test \
-H "Authorization: Bearer $ENDVR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "type": "code.deactivate" }'The answer says whether your endpoint answered 2xx.
Rotate the secret
PUT /webhooks with "rotateSecret": true returns a new secret. For 24 hours, events carry signatures from both the
old and the new secret, so you can deploy the new one without missing events.
When deliveries keep failing
GET /webhooks shows failingSince, and the brand sees the failures in the Brand Portal. Fix the endpoint; events
still within their 24 hours of retries are delivered.