Event delivery

Webhooks

Receive signed lifecycle events at an application-owned endpoint with retry delivery and stable event identifiers.

Configure an endpoint

1. 1Open the application Webhooks tab
2. 2Add an HTTPS backend endpoint
3. 3Select only required events
4. 4Copy the one-time signing secret into a secret manager
5. 5Send a test event
6. 6Verify signatures using the raw body
7. 7Persist event IDs before side effects

Delivery format

POST /webhooks/unifyid HTTP/1.1
Content-Type: application/json
User-Agent: UnifyID-Webhooks/1.0
UnifyID-Event-Id: EVENT_UUID
UnifyID-Event-Type: consent.revoked
UnifyID-Signature: t=TIMESTAMP,v1=HEX_HMAC

{"id":"EVENT_UUID","type":"consent.revoked","createdAt":"...","data":{...}}

Verify the signature

import crypto from "node:crypto";

export function verify(rawBody, signatureHeader, secret) {
  const values = Object.fromEntries(
    signatureHeader.split(",").map(part => part.split("="))
  );
  if (Math.abs(Date.now() / 1000 - Number(values.t)) > 300) return false;
  const expected = Buffer.from(
    crypto.createHmac("sha256", secret)
      .update(`${values.t}.${rawBody}`)
      .digest("hex"),
    "hex"
  );
  const received = Buffer.from(values.v1, "hex");
  return received.length === expected.length &&
    crypto.timingSafeEqual(received, expected);
}

Events

Retries

Any 2xx completes delivery. Network errors, redirects, timeouts, and non-2xx responses retry after 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours, and 24 hours. The event ID remains unchanged across attempts.

Receiver rules

Read the raw body before JSON parsing, enforce the five-minute timestamp tolerance, use timing-safe comparison, and ignore duplicate event IDs. Rotate a signing secret immediately after suspected exposure.

Management endpoints