> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.theary.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook config

> Per-order webhook endpoints, retry policy, and signing settings.

# Webhook config

Per-order webhook routing, retry policy, and signing settings.

## Fields

| Field               | Required | Type      | Description                                                                                                                                                                   |         |                                                                                                                                                    |
| ------------------- | -------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`           | No       | `boolean` | Enables or disables webhooks for this verification request. Default: `true`.                                                                                                  |         |                                                                                                                                                    |
| `secret`            | No       | `string`  | Secret used for HMAC-SHA256 signature generation.                                                                                                                             |         |                                                                                                                                                    |
| `retryAttempts`     | No       | `number`  | Number of retry attempts for failed webhook deliveries. Default: `3`. Delivery clamps retries to at most 10; values outside `0–10` are accepted but clamped at delivery time. |         |                                                                                                                                                    |
| `closeoutEndpoints` | No       | `object`  | Map of search type to webhook target(s). Supports URL strings, single target objects, or arrays. See [Closeout endpoints](/api-reference/schemas/closeout-endpoints).         |         |                                                                                                                                                    |
| `fallbackEndpoint`  | No       | \`string  | object                                                                                                                                                                        | array\` | Fallback target(s) used when no specific search-type closeout endpoint is configured. See [Webhook target](/api-reference/schemas/webhook-target). |

## Example

```json theme={null}
{
  "enabled": true,
  "secret": "webhook-secret-for-hmac-validation",
  "retryAttempts": 3,
  "closeoutEndpoints": {
    "EMPLOYMENT": [
      {
        "url": "https://client.example.com/webhooks/employment-closeout",
        "headers": { "X-Customer": "acme" },
        "events": ["verification.completed"]
      },
      {
        "url": "https://client.example.com/webhooks/employment-notifications",
        "events": ["verification.notification"]
      }
    ],
    "EDUCATION": [
      {
        "url": "https://client.example.com/webhooks/education-closeout",
        "basicAuth": { "username": "api", "password": "secret" },
        "events": ["verification.completed"]
      }
    ]
  },
  "fallbackEndpoint": [
    {
      "url": "https://client.example.com/webhooks/all-events",
      "events": ["verification.action_required"],
      "searchTypes": ["EMPLOYMENT", "EDUCATION"]
    }
  ]
}
```

## Behavior

### Endpoint resolution priority

1. **Search-specific endpoint**: If a closeout endpoint is configured for the specific search type (e.g., `EMPLOYMENT`), that endpoint is used
2. **Fallback endpoint**: If no search-specific endpoint is configured, the fallback endpoint is used
3. **Organization-level configuration**: If no request-level webhook configuration is provided, organization-level webhook settings are used

### Retry policy

* Failed webhook deliveries are retried up to the specified `retryAttempts` number
* Retries use exponential backoff with jitter
* After all retries are exhausted, the webhook is marked as failed

### Security

* All webhook payloads are signed using HMAC-SHA256 with the provided `secret`
* The signature is included in the `X-Webhook-Signature` header
* Verify the signature to ensure webhook authenticity

## Validation rules

* **URL Format**: Endpoint URLs must be valid URLs. Production webhook delivery requires HTTPS; non-production may also accept `http://localhost` and `http://127.0.0.1` for local testing.
* **Multiple Targets**: Each search type can define multiple webhook targets
* **Event Filters**: When `events` is omitted, the target receives only `verification.completed` (backward compatible)
* **Per-Target Security**: Per-target `secret` overrides the global `secret`; `basicAuth` adds `Authorization: Basic ...`

## Related schemas

* [Closeout endpoints](/api-reference/schemas/closeout-endpoints) — Search type specific endpoints
* [Webhook target](/api-reference/schemas/webhook-target) — Single webhook target definition
* [Verification request](/api-reference/schemas/verification-request) — Main verification request schema