Webhooks

DAL’s webhook system allows you to receive real-time notifications about important events in your compliance monitoring workflow. This guide will help you set up and integrate with our webhook system.

Overview

Webhooks are HTTP callbacks that notify your application when specific events occur in the DAL system. Instead of polling our API for updates, you can register a webhook endpoint to receive instant notifications.

Available Events

The list of supported DAL webhook events is available here.

Setting Up Webhooks

1. Configure Your Endpoint

First, you need to set up a webhook endpoint in your application that can receive HTTP POST requests. Your endpoint should:

Accept JSON payloads
Return HTTP 200 status for successful processing
Handle the handshake challenge (see below)
Process webhook events within 5 seconds

2. Register with DAL

Contact your DAL administrator to register your webhook endpoint. You’ll need to provide:

Webhook URL: The HTTPS endpoint where you want to receive webhooks
Shared Secret: A secret key used for HMAC signature verification
Tenant Name: Your organization’s tenant identifier

3. Handle the Handshake

When you register a webhook, DAL will send a handshake event to verify your endpoint is working. Your endpoint must:

Receive the handshake event
Verify the HMAC signature (see Security section)
Return the challenge string in the response

Handshake Response Format:

{
  "eventType": "Handshake",
  "challenge": "received-challenge-string"
}

Webhook Statuses

DAL tracks the status of your webhook integration to ensure reliable delivery of events. Understanding webhook statuses helps you monitor the health of your integration and troubleshoot issues.

Available Statuses

Active

Status: Active When your webhook is in Active status:

Webhook events are being sent to your endpoint normally
All configured events (EntityStatusUpdate, MonitoredEntityUpdate, etc.) will be delivered
Handshake verification is passing
Your endpoint is responding successfully to webhook requests

This is the normal operating state for a healthy webhook integration.

Paused

Status: Paused When your webhook is in Paused status:

Webhook events are not being sent to your endpoint but are being tracked by our system
Events are queued and will be dispatched on your demand when the status returns to Active
This status is automatically set by DAL when issues are detected
This status indicates that handshake verification is failing or webhook delivery is consistently failing

When Paused Status is Automatically Set?:

Handshake Failures: After 3 consecutive handshake failures, DAL automatically pauses your webhook to prevent further failed attempts
Delivery Failures: After 5 consecutive failed webhook delivery attempts, DAL automatically pauses your webhook

When your webhook is paused, DAL will continue to queue events. Once the status returns to Active, queued events will be retried on your demand, not automatically.

Disabled

Status: Disabled When your webhook is in Disabled status:

Webhook events are not being sent to your endpoint nor tracked
This status is manually set by a DAL administrator or when you are newly onboarded to Dal and did not set up webhooks yet
Events are not queued while disabled

This status is typically used for administrative purposes when you need to completely stop webhook delivery or as an inital status before webhook integration.

Status Transitions

Webhook statuses can transition based on system behavior and administrative actions:

Automatic Transitions

Active → Paused:
- Occurs automatically when handshake verification fails 3 consecutive times
- Occurs automatically when webhook delivery fails after 5 attempts
- Events are queued but not dispatched
Paused → Active:
- Occurs automatically when a handshake verification succeeds after being paused
- Failed handshake counter is reset to 0
- Queued events will be retried once status becomes Active [ On Demand ]

Manual Transitions

Any Status → Disabled:
- Set manually by DAL administrators
- Used to completely stop webhook delivery
- Events are not queued while disabled
Disabled → Active:
- Set manually by DAL administrators
- Used to enable webhook delivery after setting up your intergration or after maintenance if was turned off
Paused → Disabled:
- Set manually by DAL administrators
- Used when you want to stop queuing events while paused

Understanding Status Behavior

When Webhook is Active:

All events are delivered immediately
Failed deliveries are retried up to 5 times
Handshake verification runs periodically to ensure endpoint health

When Webhook is Paused:

Events are queued but not delivered
Failed handshake counter tracks consecutive failures
Once handshake succeeds, status automatically returns to Active and queued events can be dispatched as per your request
Maximum of 3 consecutive handshake failures triggers Paused status

When Webhook is Disabled:

No events are delivered or queued
Status must be manually changed by administrator
Used for maintenance or when you want to completely stop webhook delivery

Monitoring Your Webhook Status

You can check your webhook status programmatically using the Get Webhook Status API endpoint, or contact your DAL administrator. They can:

View your current webhook status
Check failed handshake counts
Review webhook delivery logs
Manually change your webhook status if needed

Using the API:

curl -X GET "https://api.getdal.com/services/crm/webhook/status" \
  -H "x-tenant: your-tenant-name" \
  -H "x-api-key: your-api-key"

If your webhook is automatically paused, DAL administrators are notified, and they can help troubleshoot the issue with your endpoint.

Security

HMAC Signature Verification

All webhook requests include an HMAC signature in the x-signature header. You must verify this signature to ensure the request came from DAL. Signature Generation:

signature = HMAC-SHA256(webhook_secret, request_body)

Example Implementation (Node.js):

const crypto = require("crypto");

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(payload, "utf8")
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expectedSignature, "hex"),
  );
}

// In your webhook handler
app.post("/webhook", (req, res) => {
  const signature = req.headers["x-signature"];
  const payload = JSON.stringify(req.body);

  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }

  // Process webhook
  res.status(200).send("OK");
});

Example Implementation (Python):

import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, expected_signature)

# In your webhook handler
@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('x-signature')
    payload = request.get_data(as_text=True)

    if not verify_webhook_signature(payload, signature, WEBHOOK_SECRET):
        return 'Invalid signature', 401

    # Process webhook
    return 'OK', 200

Testing Your Integration

1. Test Webhook Endpoint

Use the integration test endpoint to verify your webhook is working:

curl -X POST "https://api.getdal.com/crm/webhook/test" \
  -H "Content-Type: application/json" \
  -H "x-tenant: your-tenant-name" \
  -d '{"message": "Test webhook integration"}'

This will trigger an IntegrationTestUpdate event to your registered webhook URL.

2. Verify Handshake

When you register your webhook, DAL will automatically send a handshake event. Make sure your endpoint:

Receives the handshake
Verifies the signature
Returns the correct response format

Best Practices

1. Idempotency

Webhook events may be delivered multiple times. Implement idempotency in your webhook handler to avoid processing the same event twice. Example:

const processedEvents = new Set();

app.post("/webhook", (req, res) => {
  const eventId = `${req.body.eventType}-${req.body.timestamp}-${req.body.data.entity.id}`;

  if (processedEvents.has(eventId)) {
    return res.status(200).send("Already processed");
  }

  processedEvents.add(eventId);

  // Process webhook
  res.status(200).send("OK");
});

2. Error Handling

Always return HTTP 200 for successful processing, even if you encounter errors. Log errors internally and handle them appropriately.

app.post("/webhook", (req, res) => {
  try {
    // Process webhook
    processWebhookEvent(req.body);
    res.status(200).send("OK");
  } catch (error) {
    console.error("Webhook processing error:", error);
    // Still return 200 to prevent retries
    res.status(200).send("Error logged");
  }
});

3. Timeout Handling

Process webhook events quickly. DAL has a 5-second timeout for webhook responses.

4. Logging

Log all webhook events for debugging and audit purposes:

app.post("/webhook", (req, res) => {
  console.log("Received webhook:", {
    eventType: req.body.eventType,
    timestamp: req.body.timestamp,
    entityId: req.body.data?.entity?.id,
  });

  // Process webhook
  res.status(200).send("OK");
});

Troubleshooting

Common Issues

Invalid Signature: Ensure you’re using the correct shared secret and computing the HMAC signature properly.
Handshake Failure: Make sure your endpoint returns the exact challenge string in the handshake response.
Timeout Errors: Process webhook events quickly and return a response within 5 seconds.
Missing Headers: Ensure your endpoint can receive the x-signature header.

Debug Mode

Enable debug logging in your webhook handler to troubleshoot issues:

app.post("/webhook", (req, res) => {
  console.log("Headers:", req.headers);
  console.log("Body:", req.body);
  console.log("Signature:", req.headers["x-signature"]);

  // Process webhook
  res.status(200).send("OK");
});

Support

If you encounter issues with webhook integration:

Check the webhook test endpoint to verify connectivity
Review your signature verification implementation
Ensure your endpoint handles all required event types
Contact your DAL administrator for assistance

API Reference

Test Webhook Endpoint

POST /crm/webhook/test Triggers an integration test webhook event. Headers:

x-tenant: Your tenant name
Content-Type: application/json

Request Body:

{
  "message": "Test message"
}

Response:

{
  "status": "Dummy Event dispatched",
  "tenant": "your-tenant-name",
  "message": "Test message",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Health Check

GET /crm/webhook/health Check if the webhook service is running. Response:

{
  "status": "OK",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Get Webhook Status

GET /crm/webhook/status Retrieve the current webhook status for your tenant. This endpoint allows you to check whether your webhook integration is Active, Paused, or Disabled. Headers:

x-tenant: Your tenant name
x-api-key: Your API key

Response:

{
  "status": "Active",
  "tenant": "your-tenant-name",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Possible Status Values:

Active - Webhooks are being sent normally
Paused - Webhook delivery is temporarily paused (events are queued)
Disabled - Webhook delivery is disabled (events are not queued)

Use Cases:

Monitor webhook integration health
Troubleshoot webhook delivery issues
Verify webhook status after configuration changes

Getting Started

Integration

Transaction Monitoring

Breaking Changes

Overview

Available Events

Setting Up Webhooks

1. Configure Your Endpoint

2. Register with DAL

3. Handle the Handshake

Webhook Statuses

Available Statuses

Active

Paused

Disabled

Status Transitions

Automatic Transitions

Manual Transitions

Understanding Status Behavior

Monitoring Your Webhook Status

Security

HMAC Signature Verification

Testing Your Integration

1. Test Webhook Endpoint

2. Verify Handshake

Best Practices

1. Idempotency

2. Error Handling

3. Timeout Handling

4. Logging

Troubleshooting

Common Issues

Debug Mode

Support

API Reference

Test Webhook Endpoint

Health Check

Get Webhook Status

​Overview

​Available Events

​Setting Up Webhooks

​1. Configure Your Endpoint

​2. Register with DAL

​3. Handle the Handshake

​Webhook Statuses

​Available Statuses

​Active

​Paused

​Disabled

​Status Transitions

​Automatic Transitions

​Manual Transitions

​Understanding Status Behavior

​Monitoring Your Webhook Status

​Security

​HMAC Signature Verification

​Testing Your Integration

​1. Test Webhook Endpoint

​2. Verify Handshake

​Best Practices

​1. Idempotency

​2. Error Handling

​3. Timeout Handling

​4. Logging

​Troubleshooting

​Common Issues

​Debug Mode

​Support

​API Reference

​Test Webhook Endpoint

​Health Check

​Get Webhook Status

Overview

Available Events

Setting Up Webhooks

1. Configure Your Endpoint

2. Register with DAL

3. Handle the Handshake

Webhook Statuses

Available Statuses

Active

Paused

Disabled

Status Transitions

Automatic Transitions

Manual Transitions

Understanding Status Behavior

Monitoring Your Webhook Status

Security

HMAC Signature Verification

Testing Your Integration

1. Test Webhook Endpoint

2. Verify Handshake

Best Practices

1. Idempotency

2. Error Handling

3. Timeout Handling

4. Logging

Troubleshooting

Common Issues

Debug Mode

Support

API Reference

Test Webhook Endpoint

Health Check

Get Webhook Status