---
icon: webhook
label: Webhook support
order: 650
expanded: false
---

# 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](/rest-api/verifeye-service-api/#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:**

```json
{
  "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.

!!!tip
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](/rest-api/verifeye-service-api/#get-session-result) endpoint from your server using the received `verificationSessionId`.

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

[!ref text="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.

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

[!ref text="Webhook configuration settings"](/redirect/verification-configurations/#webhook-configuration)

[!ref text="Configure via VerifEye Service API"](/rest-api/verifeye-service-api/#create-verification)

---

*Last updated: 2026-03-31*