Skip to Content
Developers

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

EventWhenWhat to do
code.deactivateA 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.endedThe 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:

HeaderContent
webhook-idThe event id, the same on every retry.
webhook-timestampSeconds since the Unix epoch when this attempt was signed.
webhook-signatureOne 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:

  1. Reject the request if webhook-timestamp is more than 5 minutes from your clock.
  2. Compute the signature over the raw body, before any JSON parsing.
  3. Accept the request if any v1 value in webhook-signature matches, 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 2xx as 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-id to 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.

On this page