Webhooks API

Manage webhooks programmatically. Subscribe to specific event types and receive real-time notifications.

Event Types

Subscribe to specific events or use all to receive all events.

Onboarding Session Events

High-level lifecycle events for the OnboardingSession — the magic-link container sent to an entity that may wrap a DDQ response, an identity verification, or both.

Event Type	Description
`onboarding.created`	Onboarding link generated and sent to the entity
`onboarding.ddq_completed`	Entity finished the DDQ step within the onboarding session
`onboarding.verification_completed`	Entity finished the identity verification step within the onboarding session
`onboarding.completed`	All required steps completed — entity fully onboarded
`onboarding.expired`	Onboarding link expired before entity completed all steps
`onboarding.revoked`	Onboarding link permanently revoked by your team
`onboarding.link_regenerated`	A new token issued for an existing session (resend / refresh link)

Response Workflow Events

Event Type	Description
`response.created`	New response (DDQ submission) created
`response.submitted`	Entity submitted completed response
`response.reviewed`	Response reviewed by compliance team
`response.approved`	Response approved
`response.rejected`	Response rejected
`response.autofill_completed`	AI autofill process completed
`response.check_answers_completed`	AI answer checking completed
`response.autoflag_completed`	AI autoflag analysis completed

AML Screening Events

Event Type	Description
`screening.completed`	AML screening check finished successfully
`screening.failed`	AML screening encountered an error
`batch.completed`	Batch screening operation completed
`batch.progress`	Batch screening progress update
`batch.failed`	Batch screening operation failed

Identity Verification Events

Event Type	Description
`verification.session_created`	New identity verification session started
`verification.session_accessed`	Verification session accessed by entity
`verification.session_completed`	Verification session completed successfully
`verification.session_failed`	Verification session failed
`verification.session_expired`	Verification session expired
`verification.check_completed`	Identity verification check completed
`non_document.check_initiated`	Non-document check initiated
`non_document.completed`	Non-document check completed with results
`non_document.reviewed`	Non-document check reviewed

Case & Alert Events

Event Type	Description
`case.opened`	New case opened for investigation
`case.resolved`	Case resolved or closed
`alert.created`	New alert created

Special Event Types

Event Type	Description
`all`	Subscribe to all event types (wildcard subscription)
`test`	Synthetic test event fired by the `POST /api/v1/webhooks/test/` endpoint

Create Webhook

POST /api/v1/webhooks/

Subscribe to a specific event type. Create multiple subscriptions to handle different events with different endpoints.

Request Body

Field	Type	Required	Description
`event_type`	string	Yes	Event type to subscribe to (see event types table above)
`webhook_url`	string	Yes	Your webhook endpoint URL (must be HTTPS)
`description`	string	No	Human-readable description
`filters`	object	No	Optional event filters (for future use)

Save Your Secret Key

The secret_key is returned only once during creation. Store it securely to verify webhook signatures.

Response (201 Created)

{
  "id": "f67f165d-0d1e-4eb7-81e6-3494a260dcd4",
  "event_type": "screening.completed",
  "webhook_url": "https://api.yourcompany.com/webhooks/screening",
  "secret_key": "whsec_A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6",
  "message": "Webhook created successfully"
}

List Webhooks

GET /api/v1/webhooks/

Get all webhooks for your API key.

Response (200 OK)

{
  "webhooks": [
    {
      "id": "f67f165d-0d1e-4eb7-81e6-3494a260dcd4",
      "event_type": "screening.completed",
      "webhook_url": "https://api.yourcompany.com/webhooks/screening",
      "is_active": true,
      "description": "Production screening webhook",
      "filters": {},
      "created_at": "2026-01-19T10:30:00.123456+00:00",
      "stats": {
        "total_deliveries": 127,
        "successful_deliveries": 125,
        "failed_deliveries": 2
      },
      "last_triggered_at": "2026-01-22T08:15:30.987654+00:00"
    },
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "event_type": "case.resolved",
      "webhook_url": "https://api.yourcompany.com/webhooks/cases",
      "is_active": true,
      "description": "Case resolution notifications",
      "filters": {},
      "created_at": "2026-01-18T14:20:00.123456+00:00",
      "stats": {
        "total_deliveries": 43,
        "successful_deliveries": 43,
        "failed_deliveries": 0
      },
      "last_triggered_at": "2026-01-21T16:45:22.543210+00:00"
    }
  ]
}

Response Fields

Field	Type	Description
`id`	uuid	Webhook identifier
`event_type`	string	Subscribed event type
`webhook_url`	string	Webhook endpoint URL
`is_active`	boolean	Whether webhook is active
`description`	string	Webhook description
`filters`	object	Event filters (if any)
`created_at`	string	ISO 8601 timestamp
`stats`	object	Delivery statistics
`last_triggered_at`	string	Last delivery timestamp (null if never triggered)

Get Webhook

GET /api/v1/webhooks/{webhook_id}/

Get detailed information about a specific webhook.

Path Parameters

Parameter	Type	Description
`webhook_id`	uuid	Webhook identifier

Response (200 OK)

{
  "id": "f67f165d-0d1e-4eb7-81e6-3494a260dcd4",
  "event_type": "screening.completed",
  "webhook_url": "https://api.yourcompany.com/webhooks/screening",
  "is_active": true,
  "description": "Production screening webhook",
  "filters": {},
  "created_at": "2026-01-19T10:30:00.123456+00:00",
  "updated_at": "2026-01-19T10:30:00.123456+00:00",
  "stats": {
    "total_deliveries": 127,
    "successful_deliveries": 125,
    "failed_deliveries": 2
  },
  "last_triggered_at": "2026-01-22T08:15:30.987654+00:00"
}

Update Webhook

PATCH /api/v1/webhooks/{webhook_id}/

Update webhook settings. All fields are optional.

Path Parameters

Parameter	Type	Description
`webhook_id`	uuid	Webhook identifier

Request Body

Field	Type	Description
`webhook_url`	string	New webhook URL
`is_active`	boolean	Enable/disable webhook
`description`	string	Updated description
`filters`	object	Updated filters

Response (200 OK)

{
  "message": "Webhook updated",
  "id": "f67f165d-0d1e-4eb7-81e6-3494a260dcd4"
}

Delete Webhook

DELETE /api/v1/webhooks/{webhook_id}/

Permanently delete a webhook. This action cannot be undone.

Path Parameters

Parameter	Type	Description
`webhook_id`	uuid	Webhook identifier

Response (200 OK)

{
  "message": "Webhook deleted successfully"
}

Test Webhook

POST /api/v1/webhooks/test/

Synchronously deliver a test event to the given URL and return the outcome. Delivery happens inline — no Celery worker is required. Accepts both API key and session (browser) authentication.

Request Body

Field	Type	Required	Description
`webhook_url`	string	Yes	HTTPS URL to deliver the test event to

Response (200 OK — delivery succeeded)

{
  "success": true,
  "message": "Test webhook delivered successfully",
  "log_id": 4821,
  "http_status_code": 200
}

Response (502 — delivery failed)

{
  "success": false,
  "message": "Test webhook delivery failed: HTTP 404: Not Found",
  "log_id": 4822,
  "http_status_code": 404
}