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.

​
Fields

​
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