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 four session webhooks available:

• Session Started: Triggered when any session triggered by a Flow or Workflow starts.
• 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.

---

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

The 6 fields explained in the following table are common to all session webhook notifications. They are the only fields included in SESSION_STARTED.

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

The final table explains the single field included only in session webhook notifications for SESSION_SUCCEEDED.

---

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.