Configuration: Webhooks Tab

This tab shows information about your configured webhooks.

On the Webhooks tab, you can also:

Configure general webhook settings
Configure new webhooks
Edit existing webhook configurations
Delete existing webhook configurations

Understand Webhooks

Webhooks are event notifications. They let your 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; communication flows only from the Incode Platform to your application. You must configure them before you can use them.

The following webhooks are currently available:

Onboarding status webhook: Triggered every time an Onboarding Session status changes. Learn more.
Videoselfie uploaded webhook: Triggered when the video selfie recording file becomes available. Learn more.
Third party async retries webhook:
Watchlist updated webhook: Triggered when a global watchlist result is updated. Learn more.
Work history callback: Triggered after a work history search for a user is processed. This webhook is for Mexico only. Learn more.
Proof of payment callback: Triggered after payment proof validation for a user is processed. This webhook is for Mexico only. Learn more.
Face Authentication: Triggered when face authentication succeeds or fails. Learn more.
Session Started: Triggered when any session from a Flow or Workflow starts. Learn more.
Session Failed: Triggered when any session from a Flow or Workflow fails. Learn more.
Session Succeeded: Triggered when any session from a Flow or Workflow succeeds. Learn more.
Session Pending Review: Triggered when any session from a Flow or Workflow requires manual review. Learn more.

The following webhooks are deprecated:

INE scraping webhook: Provided INE scraping results.
Authentication webhooks: Contained information about the login attempt, matching identities, and the interview which best matched the biometric of the face used to log in. These webhooks were available for 1:1 and 1:N.

Webhook Configurations

The Webhook configurations table shows the fields for each configured webhook.

Field	Description
ID	Unique identifier Incode assigned to the webhook configuration.
Type	The name of the webhook as shown in the drop-down when it was configured: for example, Onboarding Status Webhook URL.
URL	The URL webhook notifications are sent to. Provided when the webhook was configured.
Actions	Icons to Edit Webhook or Delete Webhook.

Configure General Webhook Settings

The settings in this section of the Webhooks tab apply to all your webhooks.

Field	Description
Authentication URL (Optional)	Only needed if you have configured webhook authorization using OIDC. Incode provides this URL when you set up OIDC authorization.
Client ID (Optional)	Only needed if you have configured webhook authorization using OIDC. When you set up OIDC authorization, Incode provides this value. It's also known as a client secret.
Secret Key (Optional)	Only needed if you have configured webhook authorization using OIDC. Incode provides this value when you set up OIDC authorization.
Client Authentication (Required)	Select one of the following from the drop-down: Send as Basic Auth Header or Send Client Credentials in Body.
Scopes (Optional)	Only needed if you have configured webhook authorization using OIDC.
Webhook Custom Body Parameters	Creates key/value pairs that are included in the OAuth token request sent to your authorization server when Incode obtains a token to deliver webhooks. Useful for passing values your identity provider requires, such as `scope`, `audience`, `resource`, or a tenant identifier. Click Add to expose the following fields: Custom Body Parameter Key and Custom Body Parameter Value. `client_id` and `client_secret` are reserved and can't be used as keys.
Webhook Custom Headers (Optional)	Creates custom headers that your endpoint receives as part of webhook notifications. All headers are sent for all webhooks. Dynamic values are not supported. Click Add to expose the following fields: Custom Header Key and Custom Header Value. You can add more than one header.

In the left menu, click Configuration.
Click the Webhooks tab.
If you want to use authentication, enter values in Authentication URL, Client ID, and Secret Key.
Select a value from the Client Authentication drop-down.
Enter values in Scopes if needed.
To use custom headers, click the plus sign (+) and enter values in Custom Header Name and Custom Header Value.
Click Update Settings.

Configure New Webhook

In the left menu, click Configuration.
Click the Webhooks tab.
Scroll down and click Generate New in the lower right corner.
Use the drop-down to select the Type of webhook you want to configure.
Enter the URL for this webhook to use. Only one URL per webhook is supported. If you need to send the webhook notification to more than one endpoint, broadcast it internally after receiving it at this URL.

Configure Watchlist Update Webhook

To receive notifications when watchlist search results change, configure a webhook and enable the Subscribe for updates setting in your Watchlist Business module.

In the left menu, click Configuration.
Click the Webhooks tab.
In the Webhook configurations table, find the Watchlist update webhook url webhook and click Edit.
Add your webhook URL and click Save.
Run a search against POST /omni/businessWatchlist-result with "subscribe": true in the request body. At minimum, the request body must include:
- businessName: Required. String. Name of the business.
- country: Optional. String. Two-letter ISO 3166-1 alpha-2 country code.
Save the ref value from the response. This identifies the search when updates arrive.
When the search results are updated, Incode sends the saved ref to your webhook.
Call GET /omni/updated-watchlist-result?ref=[ref] to retrieve the updated results.

The webhook request body includes three fields:

Field	Type	Description
interviewId	String	Session ID
ref	String	Reference number for the search
search_id	String	ID assigned when the search was created

Edit Existing Webhook Settings

In the left menu, click Configuration.
Click the Webhooks tab.
In the Webhook configurations table, locate the webhook you want to change and click Edit.
Enter new values as needed. Click Save.

Delete Existing Webhook

In the left menu, click Configuration.
Click the Webhooks tab.
In the Webhook configurations table, locate the webhook you want to delete and click Delete.
In the confirmation dialog, click Confirm.