Webhook support

The webhook feature allows your server to receive an automatic notification when a verification session completes. Instead of polling for results, you configure an endpoint on your server and VerifEye will call it as soon as the outcome is available.

How it works

When a verification session finishes — regardless of outcome — the service sends an HTTP POST request to the eventCallbackUrl configured on the verification. The request body contains the event name and the verification session ID.

Your server can then call the Get Session Result endpoint with that session ID to retrieve the full verification results.

Event payload

The webhook request is a POST with the following headers and JSON body:

Request headers:

Header	Description
`Content-Type`	`application/json`
`X-API-Key`	Your account API key. Use this to verify the request originates from VerifEye.

Request body:

{
  "event": "VerificationCompleted",
  "verificationSessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Field	Type	Description
`event`	string	The event type. Currently always `VerificationCompleted`
`verificationSessionId`	string	The ID of the completed verification session

Delivery behavior

The service makes one attempt to deliver the event to the configured URL.
If the response status code is not a success (2xx), the delivery is retried once.
If the retry also fails, the event is not delivered again.
Each delivery attempt has a 5-second timeout. If your endpoint does not respond within 5 seconds the attempt is treated as a failure and the retry logic applies.
Webhook failures do not affect the verification result or the user-facing redirect flow.

Your endpoint should respond with a 2xx status code as quickly as possible. Avoid performing long-running operations in the request handler — use the verificationSessionId to fetch results asynchronously instead.

Retrieving full results

The webhook payload only contains the session ID. To get the complete verification outcome, call the Get Session Result endpoint from your server using the received verificationSessionId.

curl -X GET "https://verifeye-service-api-eu.realeyes.ai/v1/verification/get-session-result?verificationSessionId=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE"

The response contains the full set of verification results, independent of what the verification configuration was set up to expose via redirect parameters.

Get Session Result — full response reference

../../rest-api/verifeye-service-api/#get-session-result

Security best practices

Authenticate incoming requests using the API key

Every webhook request includes your account API key in the X-API-Key header. Validate this value on every incoming request and reject any request that does not carry the expected key.

Handle duplicate deliveries

If the first delivery attempt fails and the retry succeeds, your endpoint may receive the same event twice. Make your handler idempotent — processing the same verificationSessionId more than once should not cause duplicate side effects.

Respond quickly — process asynchronously

Each delivery attempt times out after 5 seconds. Your endpoint must return a 2xx response within that window. Enqueue the event and process it in the background rather than doing any heavy work in the request handler itself.

Your webhook endpoint is publicly accessible. Always authenticate incoming requests using the X-API-Key header before acting on the payload.

Configuration

The webhook is configured per verification via the webhookConfig.eventCallbackUrl field on the verification configuration.

Webhook configuration settings

../verification-configurations/#webhook-configuration

Configure via VerifEye Service API

../../rest-api/verifeye-service-api/#create-verification

Last updated: 2026-03-31