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

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