# 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](https://developer.incode.com/docs/onboarding-status-webhook).
- **Videoselfie uploaded webhook**: Triggered when the video selfie recording file becomes available. [Learn more](https://developer.incode.com/docs/video-selfie-webhook).
- **Third party async retries webhook**: 
- **Watchlist updated webhook**: Triggered when a global watchlist result is updated. [Learn more](https://developer.incode.com/docs/global-watchlists-webhook).
- **Work history callback**: Triggered after a work history search for a user is processed. This webhook is for Mexico only. [Learn more](https://developer.incode.com/docs/work-history-webhook).
- **Proof of payment callback**: Triggered after payment proof validation for a user is processed. This webhook is for Mexico only. [Learn more](https://developer.incode.com/docs/payment-proof-webhook).
- **Face Authentication**: Triggered when face authentication succeeds or fails. <Anchor target="_blank" href="https://developer.incode.com/docs/face-authentication-webhook">Learn more</Anchor>.
- **Session Started**: Triggered when any session from a Flow or Workflow starts. [Learn more](https://developer.incode.com/docs/session-webhooks).
- **Session Failed**: Triggered when any session from a Flow or Workflow fails. <Anchor target="_blank" href="https://developer.incode.com/docs/session-webhooks">Learn more</Anchor>.
- **Session Succeeded**: Triggered when any session from a Flow or Workflow succeeds. [Learn more](https://developer.incode.com/docs/session-webhooks).
- **Session Pending Review:&#x20;**&#x54;riggered when any session from a Flow or Workflow requires manual review. [Learn more](https://developer.incode.com/docs/session-webhooks).

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.                                                                                                                                                                             |

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

***

## Configure New Webhook

1. In the left menu, click **Configuration**.
2. Click the **Webhooks** tab.
3. Scroll down and click **Generate New** in the lower right corner.
4. Use the drop-down to select the **Type** of webhook you want to configure.
5. 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](https://developer.incode.com/docs/watchlist-business-dashboard#configuration-options) module.

1. In the left menu, click **Configuration**.
2. Click the **Webhooks** tab.
3. In the Webhook configurations table, find the _Watchlist update webhook url_**&#x20;**&#x77;ebhook and click **Edit**.
4. Add your webhook URL and click **Save**.
5. 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.
6. Save the `ref` value from the response. This identifies the search when updates arrive.
7. When the search results are updated, Incode sends the saved `ref` to your webhook.
8. 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

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

***

## Delete Existing Webhook

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

<br />