Skip to main content

​
WebhookConfigDto Schema

The WebhookConfigDto defines the webhook configuration for verification requests. This allows you to specify custom webhook endpoints, retry policies, and security settings for receiving notifications about verification status changes.

​
Supported Fields

FieldRequiredTypeRules and behavior
enabledNobooleanEnables or disables webhooks for this verification request. Default: true.
secretNostringSecret used for HMAC-SHA256 signature generation.
retryAttemptsNonumberNumber of retry attempts for failed webhook deliveries. Range 0–10. Default: 3.
closeoutEndpointsNoCloseoutEndpointsDtoMap of search type to webhook target(s). Supports URL strings, single WebhookTargetDto objects, or arrays. See CloseoutEndpointsDto.
fallbackEndpointNostring, WebhookTargetDto, or arrayFallback target(s) used when no specific search-type closeout endpoint is configured.

​
Complete 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"]
    }
  ]
}

​
Webhook 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. Tenant-level configuration: If no request-level webhook configuration is provided, tenant-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: All endpoint URLs must be valid HTTPS URLs
  • Retry Range: retryAttempts must be between 0 and 10
  • Secret Length: secret should be at least 16 characters for security
  • 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 ...

​
Usage

This schema is used in:

​
Next Steps