Webhooks

​

The registration model

​

The signing secret

• The full secret is returned only once, in the response to create and rotate. Store it securely the moment you receive it.
• In the list response and the dashboard, the secret is masked (for example whsec_…ab12, last 4 characters visible) so you can identify it without exposing it.
• If a secret leaks, rotate it. The old secret stops verifying deliveries immediately, so update your integration in lockstep.

​

The event envelope

{
  "id": "whd_...",
  "event": "verification.cac.completed",
  "createdAt": "2026-05-12T09:14:00.000Z",
  "data": { }
}

​

Headers

​

Verifying the signature

1. Read t and v1 from the X-Vouchmark-Signature header.
2. Build the signed payload by concatenating the timestamp, a ., and the exact raw request body (the bytes you received, before any JSON re-serialization):
   signedPayload = `${t}.${rawRequestBody}`
   
3. Compute HMAC-SHA256(signedPayload, signingSecret) and encode it as lowercase hex.
4. Compare your computed value against v1 in constant time.
5. Reject deliveries whose t is too far in the past to protect against replay attacks.

​

Node.js example

import crypto from "node:crypto";

const TOLERANCE_SECONDS = 5 * 60;

function verifyVouchmarkWebhook(rawBody, signatureHeader, signingSecret) {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((kv) => kv.split("=")),
  );
  const timestamp = Number(parts.t);
  const provided = parts.v1;
  if (!timestamp || !provided) return false;

  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > TOLERANCE_SECONDS) return false;

  const signedPayload = `${timestamp}.${rawBody}`;
  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(signedPayload)
    .digest("hex");

  const a = Buffer.from(expected);
  const b = Buffer.from(provided);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

​

Event types

​

Service types

​

Sandbox vs live

​

Reliability and retries

• Deliveries are at-least-once. The same event may arrive more than once, so dedupe on the delivery id (the whd_... value, also in X-Vouchmark-Delivery).
• Vouchmark attempts each delivery up to 5 times with exponential backoff (base 5 seconds).
• Each attempt has a 10 second request timeout.
• Respond with a 2xx status quickly and process the event asynchronously. Any non-2xx response or a timeout triggers a retry.

​

Register an endpoint

curl -X POST https://api.vouchmark.com/v1/developers/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "wgt_aBcD...",
    "environment": "live",
    "serviceType": "verification",
    "endpoint": "https://your-app.com/hooks/vouchmark"
  }'

{
  "success": true,
  "data": {
    "id": "whk_aBcD...",
    "appId": "wgt_aBcD...",
    "environment": "live",
    "serviceType": "verification",
    "endpoint": "https://your-app.com/hooks/vouchmark",
    "isActive": true,
    "signingSecret": "whsec_aBcD...",
    "createdAt": "2026-05-12T09:14:00Z"
  }
}

​

List your endpoints

curl https://api.vouchmark.com/v1/developers/webhooks \
  -H "Authorization: Bearer $TOKEN"

​

Rotate a signing secret

curl -X POST https://api.vouchmark.com/v1/developers/webhooks/whk_aBcD.../rotate-secret \
  -H "Authorization: Bearer $TOKEN"

​

Delete an endpoint

curl -X DELETE https://api.vouchmark.com/v1/developers/webhooks/whk_aBcD... \
  -H "Authorization: Bearer $TOKEN"

​

Rate limits