Webhook Notifications

Webhook Management

Webhooks are managed through the Integration tab in the Workforce Dashboard. From here, you can:

Add new webhooks: Define a webhook name, event type, destination URL, and custom headers.
View existing webhooks: See all configured webhooks in a list, including their event type, destination URL, and actions.
Edit or delete webhooks: Update webhook settings or remove them as needed.

Adding a New Webhook

To add a webhook, follow these steps:

Open the Integration Tab: Navigate to the Webhooks section.
Click “Add New Webhook”: This will open a setup form.
Configure Webhook Details:
- Webhook Name: Enter a unique and descriptive name (e.g., “Verification Updates”).
- Event Type: Select the type of event you wish to monitor (e.g., Verification Started, Verification Failed).
- Destination URL: Provide the endpoint URL where notifications should be sent (e.g., https://yourdomain.com/webhooks).
- Custom Headers (Optional): Add any required custom header key-value pairs. Use custom headers for authentication or metadata required by your system.
Save the Webhook: Click “Save” to register the webhook.

Viewing and Managing Webhooks

Once configured, all webhooks will be displayed in a tabular format, showing:

Name: The webhook name for identification.
Event: The event type the webhook listens for.
Destination URL: The endpoint where notifications are sent.
Actions: Options to edit or delete the webhook.

Available Webhook Events

The table below outlines the supported webhook events:

Event Name	Event Type	Description
Identity Enrolled	`identity.enrolled`	Triggered when an identity is first verified in your organization.
Verification Started	`verification.started`	Triggered when a verification attempt begins.
Verification Succeeded	`verification.succeeded`	Triggered when a verification attempt succeeds. Allows retrieval of user data tied to the verification ID.
Verification Failed	`verification.failed`	Triggered when a verification attempt fails. Includes detailed failure reasons such as face match failure.
Data sharing consent revoked	`identity.revoked`	Triggered when a user deletes their Incode identity or revoke data sharing consent with your organization.
Pending Manual Review	`verification.failed`	Triggered when an employee's identity attribute doesn't match what's store in the employee's IAM profile.

Notification Payload Details

Each webhook notification includes common fields for tracking and context.

All requests come as POST requests to the endpoint configured. Headers are passed as key value pairs as configure. Payload is sent in JSON format. In your internal settings make sure that Accept Application/json is configured.

Common Fields for All Webhook Notifications

Field	Type	Description
`event_id`	`string`	Unique identifier for the notification event.
`event_type`	`string`	Type of event triggering the webhook (e.g., `verification.failed`).
`timestamp`	`string`	UTC timestamp of the event in ISO 8601 format
`correlation_id`	`string`	Optional; You can provide an internal identifier at the start of verification
`data`	`object`	As described for each event type below

Webhook: Identity Enrolled

Field	Type	Description
`integration_id`	`string`	Identifier for the integration for which verification has been requested.
`identity_id`	`string`	Unique identifier of the user in Incode system.
`verification_trace_id`	`string`	Trace ID for tracking the verification process and fetching detailed result.
`user_name`	`string`	Name of the user as in the directory for whom the verification has been requested.
`user_id`	`string`	User id of the user as in the directory for whom the verification has been requested.
`workforce_user_type`	`string`	The value tells whether the verification was request for an `EMPLOYEE` or a `CANDIDATE`.
`ip`	`string`	IP address of a mobile device where verification was performed in IPv4 format.
`latitude`	`number`	IP geolocation latitude in decimal degrees.
`longitude`	`number`	IP geolocation longitude in decimal degrees.

Webhook: Verification Started

Field	Type	Description
`integration_id`	`string`	Identifier for the integration for which verification has been requested.
`verification_trace_id`	`string`	Trace ID for tracking the verification process.
`user_name`	`string`	Name of the user as in the directory for whom the verification has been requested.
`user_id`	`string`	User id of the user as in the directory for whom the verification has been requested.
`workforce_user_type`	`string`	The value tells whether the verification was request for an `EMPLOYEE` or a `CANDIDATE`.
`ip`	`string`	IP address of a mobile device where verification was performed in IPv4 format.
`latitude`	`number`	IP geolocation latitude in decimal degrees.
`longitude`	`number`	IP geolocation longitude in decimal degrees.

Webhook: Verification Succeeded

Field	Type	Description
`integration_id`	`string`	Identifier for the integration for which verification has been requested.
`verification_trace_id`	`string`	Trace ID for tracking the verification process.
`verification_id`	`string`	ID of the verification tied to the data snapshot. This value is used in the fetch verification result endpoint.
`identity_id`	`string`	Unique identifier of the user.
`user_name`	`string`	Name of the user as in the directory for whom the verification has been requested.
`user_id`	`string`	User id of the user as in the directory for whom the verification has been requested.
`enrollment_type`	`string`	In case this is a new user, the value will be `ENROLLMENT`; In case that this user is already enrolled, the value will be `RETURNING`.
`workforce_user_type`	`string`	The value tells whether the verification was request for an `EMPLOYEE` or a `CANDIDATE`.
`ip`	`string`	IP address of a mobile device where verification was performed in IPv4 format.
`latitude`	`number`	IP geolocation latitude in decimal degrees.
`longitude`	`number`	IP geolocation longitude in decimal degrees.

Webhook: Verification Failed

Field	Type	Description
`integration_id`	`string`	Identifier for the integration for which verification has been requested.
`verification_trace_id`	`string`	Trace ID for tracking the verification process.
`failure_reason`	`string`	Reason for the verification failure (e.g., `FACE_MATCH_FAILED`).
`user_name`	`string`	Name of the user as in the directory for whom the verification has been requested.
`user_id`	`string`	User id of the user as in the directory for whom the verification has been requested.
`enrollment_type`	`string`	In case this is a new user, the value will be `ENROLLMENT`; In case that this user is already enrolled, the value will be `RETURNING`.
`workforce_user_type`	`string`	The value tells whether the verification was request for an `EMPLOYEE` or a `CANDIDATE`.
`ip`	`string`	IP address of a mobile device where verification was performed in IPv4 format.
`latitude`	`number`	IP geolocation latitude in decimal degrees.
`longitude`	`number`	IP geolocation longitude in decimal degrees.

Failure Reasons Details:

Enum	Description
`FACE_MATCH_FAILED`	Selfie does not match the face image from the ID.
`ID_VALIDATION_FAILED`	ID document could not be validated.
`DATA_SHARING_CONSENT_DECLINED`	User declined to share data with the customer.
`VERIFICATION_EXPIRED`	Verification request expired before completion.
`NAME_DOES_NOT_MATCH`	Name on the ID does not match the name in the employee directory.
`EMPLOYEE_DOES_NOT_EXIST`	No employee record exists for the provided identifier.
`UNDER_REVIEW`	User’s documents are under manual review.

Webhook: Data Sharing Consent Revoked

Field	Type	Description
`identity_id`	`string`	Unique identifier of the user who deleted the identity or revoked data sharing consent.
`user_name`	`string`	Name of the user as in the directory who performed this action.
`user_id`	`string`	User id of the user as in the directory who performed this action.
`workforce_user_type`	`string`	The value tells whether the this user is an `EMPLOYEE` or a `CANDIDATE` in your organization.
`ip`	`string`	IP address of a mobile device where the action was performed in IPv4 format.
`latitude`	`number`	IP geolocation latitude in decimal degrees.
`longitude`	`number`	IP geolocation longitude in decimal degrees.

Error Handling and Retry Policy

Webhooks use an exponential backoff retry policy, making up to 5 attempts to deliver a notification in case of endpoint failures. Ensure your endpoint is ready to handle retries and process duplicate notifications gracefully.

Webhook retries will be triggered in the following scenarios:

Timeout when calling the registered endpoint.
The returned status code from registered endpoint is not 200 OK along with the application/json header or the status code 204 No content.

The retry policy for webhooks is exponential with an initial interval of 30s, multiplier of 2.5, and max attempts of 5:

Retry attempt	Delay (seconds)	Delay (minutes)	Total (minutes)
1	30	0.5	0.5
2	75	1.25	1.75
3	187.5	3.13	4.88
4	468.75	7.81	12.69
5	1 171.88	19.53	32.22

This means the maximum time a webhook can take to reach its destination is approximately 32 minutes.

Allowlist webhook source IPs

SAAS (production): IP 18.210.119.234

DEMO (development) IP 34.198.171.165

For further assistance with webhook setup or troubleshooting, contact Support.