Skip to main content

​
Working with Webhooks

This guide explains how to register webhooks, handle incoming webhook events, and understand the custom headers and payloads provided by the Diligent AI API.

​
1. Registering Webhooks

To receive webhook notifications, register your webhook endpoint via the API. You can subscribe to specific event types. Endpoint: POST /webhooks Request Example: 
{
  "webhook_url": "https://your-server.com/webhooks",
  "is_active": true,
  "secret": "your-secret",
  "events": ["cdd_state_changed", "monitoring_alert_fired", "cdd_document_fetched", "name_screening_search_completed"]
}
Supported Events:
  • cdd_state_changed: Triggered when the state of a CDD changes to inconclusive or complete.
  • monitoring_alert_fired: Triggered when a monitoring alert is fired on failure.
  • cdd_document_fetched: Triggered when a new document is successfully added to a CDD case.
  • name_screening_search_completed: Triggered when a name screening search completes and results are available.
See the Register Webhook API Reference for full details.

​
2. Receiving Webhooks

When an event occurs, Diligent AI sends an HTTPS POST request to your registered endpoint.

​
Custom Headers

Each webhook request includes custom headers to help you identify and verify the event:
HeaderDescription
Content-TypeAlways application/json
User-AgentSender identifier (e.g., DiligentAI/1.0)
X-Webhook-IdUnique ID of your webhook
X-Event-IdUnique ID of this delivery event
X-Customer-IdYour customer ID
X-Target-typeEntity type (CDD, MONITORING_ALERT, or NAME_SCREENING)
X-Event-NameName of the triggered event (CDD_STATE_CHANGED, MONITORING_ALERT_FIRED, NAME_SCREENING_SEARCH_COMPLETED, CDD_DOCUMENT_FETCHED)
X-SignatureHMAC signature for authenticity

​
Example Payloads

​
cdd_state_changed

{
  "headers": {
    "Content-Type": "application/json",
    "User-Agent": "DiligentAI/1.0",
    "X-Webhook-Id": "...",
    "X-Event-Id": "...",
    "X-Customer-Id": "...",
    "X-Target-type": "CDD",
    "X-Event-Name": "CDD_COMPLETED",
    "X-Signature": "sha256=..."
  },
  "payload": "<CDD object as JSON string>"
}

​
monitoring_alert_fired

{
  "headers": {
    "Content-Type": "application/json",
    "User-Agent": "DiligentAI/1.0",
    "X-Webhook-Id": "...",
    "X-Event-Id": "...",
    "X-Customer-Id": "...",
    "X-Target-type": "MONITORING_ALERT",
    "X-Event-Name": "MONITORING_ALERT_FIRED",
    "X-Signature": "sha256=..."
  },
  "payload": {
    "alert_id": "...",
    "monitoring_id": "...",
    "type": "FRAUD",
    "details": {
      "reason": "Suspicious activity detected",
      "triggered_at": "2025-07-31T05:12:03.123Z"
    }
  }
}
  • payload: Alert object with details about the triggered alert.

​
cdd_document_fetched

{
  "headers": {
    "Content-Type": "application/json",
    "User-Agent": "DiligentAI/1.0",
    "X-Webhook-Id": "...",
    "X-Event-Id": "...",
    "X-Customer-Id": "...",
    "X-Target-type": "CDD",
    "X-Event-Name": "CDD_DOCUMENT_FETCHED",
    "X-Signature": "sha256=..."
  },
  "payload": "<Full CDD object as JSON string>"
}
  • payload: Full CDD object snapshot including all documents (see CDD Object).

​
search_completed

{
  "headers": {
    "Content-Type": "application/json",
    "User-Agent": "DiligentAI/1.0",
    "X-Webhook-Id": "...",
    "X-Event-Id": "...",
    "X-Customer-Id": "...",
    "X-Target-type": "NAME_SCREENING",
    "X-Event-Name": "SEARCH_COMPLETED",
    "X-Signature": "sha256=..."
  },
  "payload": {
    "id": "search-id-123",
    "reference": "CUST-2024-001",
    "customer_id": "customer-123",
    "remediation_status": "COMPLETED",
    "hit_counts": {
      "FALSE_POSITIVE": 2,
      "TRUE_POSITIVE": 1,
      "UNRESOLVED": 3
    },
    "alert": {
      "reference": "WC-2024-001",
      "provider": "WORLD_CHECK",
      "status": "UNRESOLVED",
      "hits": [
        {
          "id": "hit-001",
          "status": "UNRESOLVED",
          "hit_categories": ["SANCTION"],
          "profile_fields": [...]
        }
      ]
    },
    "created_at": "2024-10-02T12:00:00Z",
    "updated_at": "2024-10-02T14:30:00Z"
  }
}
  • payload: Search object with alert and hits details from the name screening provider.

​
3. Webhook Flow Diagram

Below is a simple flow of how a webhook is triggered and received:
  • Diligent AI triggers the webhook when an event occurs.
  • Your server receives a POST request with custom headers and event payload.
  • Your server should process the event and return a 200 OK status to acknowledge receipt.
For best practices on securing your endpoint and verifying signatures, see Securing Webhooks.