🎯 Webhook Events Subscription

Webhooks now support selective event subscription, allowing you to control which events trigger notifications to your endpoint.
When creating or updating webhooks, you can now specify an optional events array to subscribe only to the events you need:
- verification.completed - Triggered when a verification is fully completed with all data available
- verification.historical - Triggered when historical data becomes available during verification processing
If the events parameter is not provided, webhooks default to all available events (backward compatible behavior).
This feature helps reduce unnecessary webhook traffic and allows your endpoint to process only relevant events.

🆕 Updated Endpoints

POST /webhooks - Now accepts optional events parameter:

{
  "endpoint_url": "https://yourapi.com/webhook/handler",
  "description": "Production webhook",
  "events": ["verification.completed", "verification.historical"],
  "authentication": { ... }
}

PATCH /webhooks/webhook_id - Can update event subscriptions:

{
  "events": ["verification.completed"]
}

⚠️ Validation Rules

Empty array: Providing an empty events array returns a 400 Bad Request error. At least one event type must be specified.
Invalid event types: Providing unrecognized event types returns a 400 Bad Request error with details about which events are invalid.
Both error responses include the list of allowed event types for reference.

💡 What This Means for You

No breaking changes — existing webhooks continue to receive all events by default.
Reduced traffic — subscribe only to the events your application needs, minimizing unnecessary webhook calls.
Better control — easily update event subscriptions without recreating webhooks.
Common use cases:
- Subscribe only to verification.completed if you only need fully processed verifications
- Subscribe only to verification.historical if you want to process data as it becomes available
- Subscribe to both events if you need real-time updates throughout the verification lifecycle
Check our webhook documentation for more details on event types and payload structures.