Event reference
Every Auvral webhook event, field by field, with complete example payloads.
Every webhook body has the same envelope. Only type and the contents of
data.verification differ between events.
{
"id": "string",
"type": "string",
"createdAt": "ISO 8601",
"data": { "verification": { } }
}Envelope
| Field | Type | Description |
|---|---|---|
id | string | The event's id. Matches the x-auvral-event-id header and is stable across retries, so this is your deduplication key. |
type | string | One of the event types below. |
createdAt | string | When the event occurred, ISO 8601. Not when this delivery attempt was made. |
data.verification | object | The verification's state at that moment. |
data.verification
| Field | Type | Description |
|---|---|---|
id | string | The verification's permanent id. |
status | "STARTED" | "RUNNING" | "VERIFIED" | "REJECTED" | The verification's status when the event was generated. |
flowId | string | null | The flow that was run. |
flowName | string | null | The flow's display name. |
sessionId | string | null | The session this came from, the sessionId returned by POST /v1/sessions. |
referenceId | string | null | Your own identifier for the person, as you sent it on create, or the one Auvral assigned. Editing it in your dashboard changes what later events carry. Auvral never interprets it. |
metadata | object | null | The flat string key-value pairs you attached on create, unchanged, or null when you attached none. |
startedAt | string | null | When your user began, ISO 8601. |
endedAt | string | null | When the verdict was reached. null until then. |
steps | array | One entry per step in the flow, in flow order. |
steps[]
| Field | Type | Description |
|---|---|---|
name | string | The step, lowercased: document_verification, biometric_verification. |
status | "PENDING" | "RUNNING" | "VERIFIED" | "REJECTED" | PENDING means the step has no result yet. |
Every step configured on the flow appears from the first event onward, so the array length never changes. Only the statuses do.
There is no personal data anywhere in the payload: no name, no document number, no date of birth, no image.
The verification events
Your user began the verification. Sent once, whichever device they finish on.
{
"id": "1c8f2b90-3ad4-41e7-8f52-9b7c6d0e4a13",
"type": "verification.started",
"createdAt": "2026-08-25T15:11:02.884Z",
"data": {
"verification": {
"id": "b47ac10b-58cc-4372-a567-0e02b2c3d479",
"status": "STARTED",
"flowId": "3f1c9a52-4d7e-4b3a-9c21-8e5f6a0b7d34",
"flowName": "Onboarding",
"sessionId": "9b2f4c1e-7a83-4d06-b5f1-2c9e8d3a6047",
"referenceId": "user_8842",
"metadata": { "orderId": "order-8841" },
"startedAt": "2026-08-25T15:11:02.884Z",
"endedAt": null,
"steps": [
{ "name": "document_verification", "status": "PENDING" },
{ "name": "biometric_verification", "status": "PENDING" }
]
}
}
}Useful for marking a user as "in progress" and for spotting drop-off: a verification that started and never submitted was abandoned.
webhook.test
Sent only by Send test event in the dashboard. Every id is the all-zero UUID,
referenceId is the literal string test and metadata is null, so it cannot be
mistaken for a real one.
{
"id": "b1e7d3f0-9c42-4a85-b6d1-8f03e5c7a294",
"type": "webhook.test",
"createdAt": "2026-08-25T14:02:00.000Z",
"data": {
"verification": {
"id": "00000000-0000-0000-0000-000000000000",
"status": "VERIFIED",
"flowId": "00000000-0000-0000-0000-000000000000",
"flowName": "Test flow",
"sessionId": "00000000-0000-0000-0000-000000000000",
"referenceId": "test",
"metadata": null,
"startedAt": "2026-08-25T14:02:00.000Z",
"endedAt": "2026-08-25T14:02:00.000Z",
"steps": [
{ "name": "document_verification", "status": "VERIFIED" },
{ "name": "biometric_verification", "status": "VERIFIED" }
]
}
}
}Handle it explicitly: verify the signature as usual, then return 200 without touching
business state.
Ordering
Events are not guaranteed to arrive in order: a retried verification.submitted can
land after verification.succeeded. Drive your logic from type and
data.verification.status, not from arrival sequence. createdAt gives you the real
ordering if you need it.
Related
- Webhooks overview: delivery, retries, idempotency.
- Verifying signatures