Integration and webhooks

Updated on 16.01.26

5 minutes to read

Copy link

Overview

Use this technical overview to determine how to integrate SEON's identity verification solution into your application. It covers the primary integration methods and details how to use webhooks to receive real-time results to automate your workflows.

Key integration benefits

Benefit	Description
Real-time automation	Webhooks deliver immediate notifications, allowing you to build fully automated, real-time decisioning workflows without the need for polling.
Comprehensive data payload	The webhook payload is a single source of truth, containing the complete session outcome, all sub-check results and extracted data, eliminating the need for follow-up API calls.
Resilient and secure delivery	With built-in retry logic and secure signature verification, you can trust that you will receive your data reliably and safely.
Flexible integration patterns	SEON offers multiple integration options (SDKs, APIs, Hosted Flow) to fit your specific technical stack and desired user experience.

Integration options

SEON provides a couple of methods for integrating the identity verification workflow into your platform. The best choice depends on your technical requirements and desired level of customization.

SDKs (recommended): Native SDKs for iOS, Android and Web provide a complete, pre-built user interface for a frictionless user experience. They handle camera management, user guidance and secure data submission automatically.
Hosted flow: A pre-built, secure web page hosted by SEON that you can redirect users to. This is the fastest way to integrate, requiring minimal development effort. Hosted flows can be created from the Workflow runs page in SEON or by using the API endpoint.

Learn more: For detailed instructions, please refer to the dedicated Integration SDK and API developer guides.

Webhooks

Webhooks are the primary mechanism for receiving real-time notifications about the status of a verification session. Instead of polling for results, SEON will instantly send a POST request to your configured endpoint when an event occurs.

Event types

SEON sends webhooks for the following key events:

Event	Trigger
`idv:session_finished`	Fired when a verification session is completed. The status will be APPROVED, DECLINED or ABANDONED. This is the primary event for triggering your decisioning logic.
`idv:session_status_updated`	Fired when a session's status is manually changed in SEON (e.g., an analyst overrides a REVIEW case to APPROVED).

Delivery and retry logic

Immediate delivery: Webhooks are sent as soon as the event is ready.
Retry attempts: If your endpoint does not respond with a successful HTTP status (200 OK), SEON will attempt to deliver the webhook up to 5 more times with an exponential backoff.
Configurable endpoint: You can set a dedicated endpoint for IDV webhooks, which can be different from the endpoint used for the SEON Fraud API.

Payload contents

The webhook payload is a comprehensive JSON object containing all information related to the session.

Key payload fields:

session_id and final status
User information (name, email, phone)
document_check_results with all sub-check outcomes
liveness_result and face_match_result
proof_of_address_result
data_extraction object with all OCR results
duplicate_detection flag and details
timeline object with timestamps for each step of the verification process

Security and best practices

1. Verify signatures: Every webhook includes a signature in the header. Always verify this signature to ensure the request came from SEON and was not tampered with.

2. Use HTTPS: Your webhook endpoint must use a secure HTTPS connection.

3. Respond quickly: Acknowledge receipt of the webhook by returning a 200 OK status as quickly as possible. Perform any complex processing asynchronously to avoid timeouts.

4. Handle idempotency: Your system should be able to handle receiving the same webhook multiple times due to retries without causing duplicate processing.