Webhooks

Subscribe

POST /v1/webhooks
Authorization: Bearer fmk_...
Content-Type: application/json

{
  "url": "https://your-app.example/hooks/fidemark",
  "events": ["attestation.created", "attestation.revoked", "batch.completed"]
}

Response:

{
  "id": "...",
  "url": "...",
  "events": ["..."],
  "secret": "<32 hex bytes>"
}

The secret is shown exactly once. Store it now: you’ll need it to verify inbound deliveries.

Verifying delivery

Every delivery includes:

Header	Value
X-Fidemark-Event	The event type.
X-Fidemark-Delivery	UUID, unique per delivery (use it for idempotency).
X-Fidemark-Signature	sha256=<hmac of body>

Verify the HMAC against your secret:

import { createHmac } from "node:crypto";

function verify(rawBody: string, header: string, secret: string): boolean {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  return header === expected;
}

Reject the request if the signature doesn’t match: that means the delivery is forged or the body was tampered with in transit.

Retry policy

Non-2xx responses (or thrown errors) trigger retries with exponential backoff:

Attempt	Wait before next try
1 → 2	30 s
2 → 3	5 min
3 → 4	30 min
4 → 5	2 h
5 → dead	12 h after attempt 5 → no further retries

After 5 failed attempts the delivery is marked dead and held for inspection. Contact support if you need to replay dead deliveries.

Manage subscriptions

GET /v1/webhooks            # List
DELETE /v1/webhooks/{id}    # Disable (no further deliveries; existing pending ones are dropped)

Listing never returns the secret. If you’ve lost it, delete and re-create.

Idempotency

Receivers should treat repeated deliveries with the same X-Fidemark-Delivery UUID as the same event. Network blips, ambiguous 5xx responses, or scaling events can occasionally cause double-delivery: your handler should be safe to call twice with no side-effect drift.