​

Webhook config

​

Fields

​

Example

{
  "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 — Search type specific endpoints
• Webhook target — Single webhook target definition
• Verification request — Main verification request schema