​
Working with Webhooks

This guide explains how to register webhooks, handle incoming webhook events, and understand the custom headers and payloads provided by the Paylane 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"]
}
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.
See the Register Webhook API Reference for full details.

​
2. Receiving Webhooks

When an event occurs, Paylane 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 or ALERT)
X-Event-NameName of the triggered event (CDD_COMPLETED, MONITORING_ALERT_FIRED)
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": "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.

​
3. Webhook Flow Diagram

Below is a simple flow of how a webhook is triggered and received:
  • Paylane 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.