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.