Documentation

Webhooks

Thirteen events, signed and retried — and how to verify one correctly.

The events

Event Fires when
credential.issued The record is created, before anything is published
credential.published It becomes public. This is the one that bills and emails
credential.updated Its expiry changes
credential.corrected A replacement is issued
credential.suspended A temporary hold
credential.unsuspended The hold is lifted
credential.revoked Withdrawn for good
credential.expired Its validity period ended
credential.renewed A new term was issued because the last one lapsed
credential.accepted An offer letter was accepted
credential.verified Somebody checked it
change.requested A recipient reported a mistake from the check page
change.decided That request was approved or rejected

Every one of them actually fires. That is worth saying out loud: the product this one is measured against emits a single event, and the research calls the gap documented and real. A test here scans the source and fails if any event in the published catalogue has no emitter — because an event that can be subscribed to and never arrives is silent in both directions.

Verifying a delivery

Every delivery is signed twice, in two header families. Use whichever suits you — they carry the same guarantee.

Standard Webhooks, if you already have a library

webhook-id: del_2KWPBgLlAfxdpx2AI54pPJ85f4W
webhook-timestamp: 1731283200
webhook-signature: v1,<base64 hmac>

The signature is HMAC-SHA256(secret, "{id}.{timestamp}.{raw body}"), base64. This is the Standard Webhooks format, so any conformant library in any language verifies our deliveries with nothing written.

Note the id is inside the signed string. That binds the signature to one delivery, so a captured body cannot be replayed under a different id.

Our own header

X-Webhook-Signature: t=1731283200,v1=<hex hmac>

HMAC-SHA256(secret, "{timestamp}.{raw body}"), hex. Compare in constant time and reject a timestamp more than a few minutes old. This header is not going anywhere; it is documented and in use, and changing what we send would break consumers that trust it.

Verify against the raw body

Before any JSON parsing. Re-serialising a parsed object changes the bytes and the signature will not match — and this is the mistake almost everybody makes. If you take one thing from this page, take that.

Rotating a secret

webhook-signature can carry several signatures, space-delimited. For twenty-four hours after you rotate, we sign with the new secret and the old one. Any one matching is a pass.

This exists because the old behaviour replaced the secret outright, which broke every delivery in flight and every consumer that had not yet deployed the new value. A secret is rotated because it leaked — under time pressure, often out of hours — which is exactly when breaking delivery costs most. Now you rotate, deploy whenever you are ready within the day, and nothing fails in between.

Rotating twice inside the window does not chain: the secret you just replaced becomes the previous one, and the older one stops immediately. A leaked secret must actually stop being valid, or rotation is theatre.

Retries

Five retries with backoff — one minute, five, thirty, two hours, twelve — after which the delivery is marked failed. Deliveries are claimed with a lease, so several workers never send the same one twice.

Answer quickly and do your own work afterwards. A webhook handler that waits for your processing is one that times out and gets retried.

For verifiers

A verifier account registers its own endpoints and receives a subset: the events that describe a credential it is watching ceasing to be reliable. See watching credentials.