Session Webhooks

Session webhooks let you set up notifications for events that happen during any session triggered by a Flow or Workflow. You can configure them, along with other types of webhooks, in Dashboard.

Learn more about webhooks

Webhooks are event notifications. They let your organization's application know when a specific event happens on the Incode platform or when a process initiated by a user is completed (also known as a callback). Your application can then take action based on the notification.

Webhooks are asynchronous (that is, the communication is only from the Incode platform to your application). You must configure them if you want to use them.

Each session webhook notifies you about a specific session event. This is different from the Onboarding Status webhook, which sends notifications at the completion of every module during a single session. Depending on the number of modules in the session Flow or Workflow, this could be more notifications than you need or want.

Session webhooks provide additional flexibility and let you tailor your notifications for specific needs.

There are six session webhooks available:

• Session Started: Triggered when any session triggered by a Flow or Workflow starts.
• Session Progress: Triggered on any /start endpoint call after the initial session creation. For example, when an end user resumes a session on their phone.
• Session Failed: Triggered when any session triggered by a Flow or Workflow fails. Sessions can fail at various points and for various reasons during a Flow or Workflow. You can view more information about failed sessions in Dashboard. Go to Dashboard > Sessions and click any session in the table to open it.
• Session Succeeded: Triggered when any session triggered by a Flow or Workflow succeeds.
• Session Pending Review: Triggered when any session triggered by a Flow or Workflow requires manual review.
• Identity Enrolled: Triggered the first time an Identity is created. Updates to an existing Identity do not emit this event.

Key facts about session webhooks

• Each session webhook notification contains a number of common fields. These provide context and allow you to track what's happening more easily.
• Notifications come as POST requests to the endpoint you configured in Dashboard.
• Notification headers are passed as key/value pairs.
• Notification payloads are sent in JSON format. You must configure any internal settings to include Accept Application/json.
• Data is included in the first notification for which it is available.

Notification payload fields

Common fields

The fields in the following table are common to all session webhook notifications (SESSION_STARTED, SESSION_PROGRESS, SESSION_FAILED, SESSION_SUCCEEDED, and SESSION_PENDING_REVIEW). They are the only fields included in SESSION_STARTED and SESSION_PROGRESS.

Fields available after a session starts

The next table explains fields that are only available after a session starts. These fields are included in SESSION_FAILED, SESSION_SUCCEEDED, or SESSION_PENDING_REVIEW notifications.

Fields available for specific event types

The following table explains fields that appear only in specific event type notifications.

Devices array

The devices field is a structured array of device objects included in SESSION_FAILED, SESSION_SUCCEEDED, and SESSION_PENDING_REVIEW notifications. It replaces the flat ip, latitude, and longitude fields previously included. However, these fields are preserved for backward compatibility. Devices are sorted by timestamp, with the oldest first.

Each device object contains the following fields:

Example:

{
  "ip": "203.0.113.10",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "browser": "Chrome",
  "deviceModel": "iPhone 15",
  "deviceType": "mobile",
  "osVersion": "iOS 17.5",
  "hash": "fingerprint-hash"
}

Failure reasons

The failureReasons field is included only in SESSION_FAILED notifications. It contains a stable, sorted, deduplicated array of identifiers indicating why the session failed.

Example:

{
  "event_type": "SESSION_FAILED",
  "failureReasons": ["ID_VALIDATION", "LIVENESS"]
}

The following table lists all possible identifiers:

Identity Enrolled webhook

The IDENTITY_ENROLLED webhook fires the first time an Identity is created. It does not fire for updates to an existing Identity.

The payload for IDENTITY_ENROLLED uses the following shape:

Example payload:

{
  "eventType": "IDENTITY_ENROLLED",
  "timestamp": "2026-05-20T14:00:00Z",
  "identityId": "65f8...",
  "interviewId": "65f7...",
  "externalId": "ext-abc-123",
  "externalCustomerId": "cust-456",
  "clientId": "client-xyz",
  "configurationId": "flow-prod-onboarding",
  "integrationReference": "ref-789"
}

Session Failed on link expiration

When a Workforce verification link expires, the platform sends a SESSION_FAILED webhook with failureReasons containing ["LINK_EXPIRED"]. This feature is configuration-dependent. Contact your Incode representative to enable it.

Error handling and retry policy

Webhooks make up to 5 attempts to deliver a notification in case of endpoint failures. You should ensure your endpoint is ready to handle retries and process duplicate notifications gracefully.

Retries will be triggered by either of these scenarios:

• A timeout is received when your endpoint is called
• A status code is returned from your service and is not either:
  • 200 OK along with the application/json header, or
  • 204 No content

The retry policy for webhooks is exponential, with an initial interval of 30 seconds and a multiplier of 2.5. The maximum number of attempts is 5. This means the maximum time a webhook can take to reach its destination is approximately 32 minutes, as illustrated in the following table.

Webhook IP address list

If your organization restricts inbound traffic for your network, make sure the following IP addresses are added to your allow list.

United States

Allow the IP addresses shown in this table for the SAAS (Production) environment.

Allow this IP address for the Demo environment.

Europe

Allow this IP address for both the Production and Demo environments.