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	String	Format: resource.action
eventDeliverId	String	Unique per retry attempt (max. 3 times)
eventSequence	String	Index of the specific event within a session (sequence: 1, 2, 3)
createdAt	ISO 8601	When the webhook was sent
environment	String	Environment on which endpoint URL was configured
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 flow
lastStepId	String	The identifier of the name. Is configurable in IDnow dashboard
lastStepType	String	Last run step
lastStepStatus	String	Status of the last step run

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, exp, and iat. Once successfully decoded and verified, the JWT payload exposes the event metadata and business data under the data field.

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",
      "lastStepId": "END-ACCEPT",
      "lastStepType": "END",
      "lastStepStatus": "COMPLETED"
    }
  },
  "iss": "https://auth.dev1.platform.idnow.dev/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	Flow is initialized and ready to start
session.completed	Flow ends with final outcome
session.expired	Flow expiry TTL reached, no longer usable
session.aborted	Flow ends by user interaction with no final outcome
session.error	Flow enters ERROR state and stops processing

---