Webhook events

Understand webhook event types and payload structure

Webhook payloads are minimal, machine-readable JSON messages that deliver metadata about an event. They will never include personally identifiable information (PII). You can fetch full details from the API when needed by using the respective session_id.

info

All events use thin payloads. No personally identifiable information (PII) is included by default. To learn more, see the Configure webhooks →

---

Payload structure

All webhook events include these fields:

Field	Type	Description
eventId	string	Same ID across retries for the same event
eventVersion	string	Current event version
eventName	enum	Format: resource.action. One of session.created, session.completed, session.aborted, session.expired, session.error (see Session events below).
eventDeliverId	number	Unique per retry attempt (currently defaulted to a max. 10 times)
eventSequence	number	Index of the specific event within a session (sequence: 1, 2, 3)
createdAt	ISO 8601	When the event was created
environment	enum	Environment on which endpoint URL was configured. One of live, staging.
payload.flowId	string	The identifier of the flow that was triggered
payload.sessionId	UUID	The identifier of the specific session
payload.sessionStatus	enum	Current status of the session. One of CREATED, RUNNING, COMPLETED, ABORTED, EXPIRED, ERROR.
payload.lastStep	object	Information about the last executed step. Always present for terminal session events (session.completed, session.aborted, session.expired, session.error). Always absent for session.created.
payload.lastStep.stepId	string	Unique identifier of the last step. This corresponds to the step name defined in the flow definition.
payload.lastStep.stepType	string	Type of the last step (e.g. DOC_ID:v2, END, CHOICE)
payload.lastStep.stepDescription	string	Human-readable description of the step (as configured in the flow). Empty string if not set.
payload.lastStep.stepStatus	string	Status of the last step. One of STARTED, COMPLETED, ERROR, ABORTED, WORKFLOW_EXPIRED, or ROLLED_BACK.
payload.lastStep.stepStatusDetails	string	Additional detail when stepStatus is ERROR (optional)

info

The eventId remains the same across all retry attempts, while eventDeliverId increments.

---

JWT-encoded payload

Webhook messages are delivered as a JSON Web Token (JWT) rather than as a plain JSON object.
The HTTP request body therefore contains a JWT string, which must be decoded to access the underlying payload.

The JWT must be verified before use, including validation of the signature and standard claims such as iss, aud, sub, exp, and iat. Once successfully decoded and verified, the JWT payload exposes the event metadata and business data under the data field.

• aud — equals the destination endpoint URL you configured for the webhook. Validate that this matches your endpoint to prevent cross-endpoint replay attacks.
• sub — equals the eventId of the delivered event.

Payload example

The decoded JWT payload has the following structure:

{
"data": {
  "eventId": "61a51c5b-480d-4f47-8334-34b0ba7ae0be",
  "eventName": "session.completed",
  "eventVersion": "1.0",
  "eventSequence": 2,
  "eventDeliverId": 1,
  "createdAt": "2026-01-08T08:35:37.581Z",
  "environment": "staging",
  "payload": {
    "flowId": "bf8e2e27-2340-426f-a0bb-f1081e4a07ac",
    "sessionId": "fe1941c2-bc45-4142-b516-fa0fc9fd7754",
    "sessionStatus": "COMPLETED",
    "lastStep": {
      "stepId": "END-ACCEPT",
      "stepType": "END",
      "stepDescription": "Final step",
      "stepStatus": "COMPLETED"
    }
  }
},
"iss": "https://localhost:3002/oidc",
"iat": 1767861339,
"exp": 1767864939,
"sub": "61a51c5b-480d-4f47-8334-34b0ba7ae0be",
"aud": "https://webhook.site/d076d490-8424-4c85-8904-5d1801c7909e"
}

---

Session events

IDnow sends the following event types when a session changes state:

Event Type	Description
session.created	The session has been created and is ready to start
session.completed	The session reached an End step with a final outcome
session.expired	The session expired before it finished and can no longer be used
session.aborted	The user left or cancelled the session before it reached a final outcome
session.error	The session stopped because of an error

session.completed means the flow finished, not that the user passed. For what to do with each event, see Interpret session results.

---

---