Webhooks

A webhook endpoint is a URL of yours that we post events to as verifications happen. It is how your own systems learn the outcome without polling us for it.

Registering an endpoint is a job for whoever runs your servers. Reading this page to find out why something did not arrive is a job for anybody.

Registering an endpoint

Give us an HTTPS URL you control. We post signed event payloads to it. The environment is fixed when the endpoint is registered and cannot be changed afterwards, so a sandbox endpoint stays a sandbox endpoint for life.

The optional description is your own label. It is worth filling in, because routing by key makes two endpoints on the same host perfectly ordinary and the name is what tells them apart in the list.

The signing secret is shown once when the endpoint is created, and once again if you rotate it. Rotating replaces it immediately with no overlap, so deliveries fail signature verification on your side until the new secret is deployed. Both actions ask for a code from your authenticator app.

Choosing events

An endpoint receives only the events it is subscribed to. Common ones:

A new endpoint starts with approved, rejected, review, expired and verification.data_updated already ticked, and you can change the selection before saving. Every endpoint that existed before applicant data could be edited, and was subscribed to at least one event, had verification.data_updated added automatically.

The full catalogue, with payloads, is in Webhook events.

An endpoint subscribed to nothing receives nothing, and the list says so plainly. So does an endpoint subscribed to an event name that nothing sends any more.

Routing by API key

Each event is matched against the API key that created the session, which is how one account running several businesses sends each one's results to its own system.

An endpoint is either set to all API keys, meaning every verification in that environment including sessions created without a key, or limited to named keys.

The console watches for the two ways this goes wrong and tells you before your customers do.

A key nothing receives. Creating an API key does not subscribe it to anything, so verifications made with it go nowhere until you add it to an endpoint or set an endpoint to all keys.

Nothing receiving keyless sessions. A verification started from this console carries no API key, so it reaches only an endpoint set to all keys. If every endpoint is limited to named keys, those sessions are delivered nowhere.

Testing before you trust it

Send a test posts a sample payload to the endpoint right now, signed with its current secret. It is about nobody: the ids inside are obviously fake and the envelope is marked as a test, so your handler can tell it apart from real traffic. The body otherwise matches what we send for real, so a handler that accepts the test accepts the real thing.

There is a short cooldown between tests.

Watching deliveries

Each endpoint has a panel showing recent traffic: everything accepted, nothing pending, nothing retried, or the failures if there are any. It says plainly when nothing has been sent at all.

Delivery history comes from the integration logs, so a role without Logs sees the endpoint but not its payloads. That limit exists because a stored payload is a verbatim copy of what we sent about an applicant.

For the full history, filters and the ability to re-send a specific delivery, go to Logs.

Disabling and deleting

Disabling stops deliveries until you re-enable it, which is what you want during maintenance on your side. Deleting is permanent, and we stop sending to that URL at all.

Neither loses the verifications. Events that could not be delivered are retried, and a delivery can be re-sent by hand afterwards.

Being told when it breaks

Add developer alert addresses in Settings and we email them when your integration drops an event. Alerts about one endpoint are grouped, so an outage is one message rather than one per lost event. Without them, nobody is told.