Webhook Overview: Real-Time Lead Events

The REST API is in early access and is enabled per account on request. API keys are not yet issued from the dashboard. To request access, contact your account executive.

DeltaLead outbound webhooks deliver HTTP POST requests to your server the moment something meaningful happens in your account — a new lead arrives, an AI agent qualifies a lead, or a test drive gets booked. Instead of polling the API on a schedule, your systems receive event data in real time with no extra latency, letting you trigger downstream workflows, update your own database, or alert your sales team the instant a hot lead appears. This page describes one direction only: DeltaLead sends events to an endpoint you own. The reverse direction — sending leads from an external system into DeltaLead — is covered by the Custom Webhook, which is available today.

Registering a Webhook Endpoint

Open Webhook Settings

In the DeltaLead dashboard, navigate to Organization → Integrations → Custom Webhooks, under the APIs and Webhooks category.

Enter Your Endpoint URL

Provide the full HTTPS URL of the server that will receive events. Plain HTTP endpoints are not accepted — DeltaLead requires a valid TLS certificate.

Select Events

Choose the specific event types you want to subscribe to. Subscribing only to the events your integration needs reduces unnecessary traffic to your server. See the full event reference for all available event types.

Save and Copy the Signing Secret

On save, DeltaLead generates an HMAC-SHA256 signing secret for the endpoint and shows it once. That secret is what verifies every incoming request, so store it in your application’s environment variables.This step cannot be performed yet. The Custom Webhooks screen currently issues inbound keys (dl_live_...), which authenticate deliveries into DeltaLead and do not verify outbound signatures. Until outbound endpoint registration exists, there is no way to obtain a signing secret from the dashboard.

Payload Structure

Every webhook POST that DeltaLead sends to your endpoint shares the same top-level structure, regardless of event type.

string

The event type that triggered this delivery, e.g. lead.qualified.

string

ISO 8601 timestamp of when the event occurred on DeltaLead’s platform.

string

The DeltaLead organization ID associated with the event.

object

Event-specific payload. The fields inside data vary by event type. See the event reference for full schemas.

lead.qualified event

{
  "event": "lead.qualified",
  "timestamp": "2024-11-07T15:30:00Z",
  "organization_id": "org_xyz789",
  "data": {
    "id": "lead_abc123",
    "status": "qualified",
    "score": 92,
    "contact": {
      "first_name": "María",
      "last_name": "García",
      "email": "maria.garcia@example.com",
      "phone": "+5491155551234"
    },
    "channels": ["whatsapp"],
    "interested_vehicles": ["veh_9f3c21"],
    "ai_summary_status": "completed"
  }
}

Verifying Webhook Signatures

DeltaLead signs every webhook request to prove the payload originated from our platform. Each delivery carries two headers.

string

Hex-encoded HMAC-SHA256 digest, computed with your endpoint’s signing secret.

string

Unix timestamp in seconds of when the delivery was sent. It is part of the signed value.

What gets signed is not the body alone, but the timestamp, a period, and the raw request body:

{X-DeltaLead-Timestamp}.{raw request body}

Verification has two steps and neither is optional. First compare the timestamp against your server clock and reject any delivery that drifts by more than 5 minutes; then recompute the HMAC over that same concatenation. The HMAC only proves where the payload came from, not that it is recent: without the tolerance window, a captured signature stays valid forever, and anyone who has seen one delivery can replay it indefinitely. Every retry is signed afresh with its own timestamp, so the window does not reject retries even when they arrive half an hour after the first attempt.

const crypto = require('crypto');

const TOLERANCE_SECONDS = 300;

function verifyWebhook(rawBody, signatureHeader, timestampHeader, secret) {
  const timestamp = Number(timestampHeader);
  if (!Number.isInteger(timestamp)) {
    return false;
  }
  const age = Math.abs(Math.floor(Date.now() / 1000) - timestamp);
  if (age > TOLERANCE_SECONDS) {
    return false;
  }
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestampHeader}.`)
    .update(rawBody)
    .digest('hex');
  if (expected.length !== signatureHeader.length) {
    return false;
  }
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300

def verify_webhook(
    raw_body: bytes,
    signature_header: str,
    timestamp_header: str,
    secret: str,
) -> bool:
    try:
        timestamp = int(timestamp_header)
    except ValueError:
        return False
    if abs(time.time() - timestamp) > TOLERANCE_SECONDS:
        return False
    signed_payload = timestamp_header.encode('utf-8') + b'.' + raw_body
    expected = hmac.new(
        secret.encode('utf-8'),
        signed_payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

const TOLERANCE_SECONDS = 300;

function verifyWebhook(
    string $rawBody,
    string $signatureHeader,
    string $timestampHeader,
    string $secret
): bool {
    if (!ctype_digit($timestampHeader)) {
        return false;
    }
    if (abs(time() - (int) $timestampHeader) > TOLERANCE_SECONDS) {
        return false;
    }
    $expected = hash_hmac('sha256', $timestampHeader . '.' . $rawBody, $secret);
    return hash_equals($expected, $signatureHeader);
}

Always use a timing-safe comparison (such as crypto.timingSafeEqual in Node.js or hmac.compare_digest in Python) to prevent timing-based attacks against the signature check.

Responding to Webhooks

Your endpoint must return an HTTP 2xx status code within 10 seconds of receiving a delivery. DeltaLead interprets any non-2xx response — or a request that times out — as a failed delivery.

Retry Policy

DeltaLead retries failed deliveries up to 3 times using exponential backoff. Retry intervals are approximately 1 minute, 5 minutes, and 30 minutes after the initial failure.

Idempotency

Because retries can result in duplicate deliveries, design your handler to be idempotent. Use event together with the resource identifier in data to deduplicate events you have already processed.

During local development, use a tunneling tool like ngrok to expose your localhost server to the internet and receive DeltaLead webhook events without deploying to a public server.

For a complete list of event types and their payload schemas, see the Webhook Event Reference.

Overview

Leads

Webhooks

Webhook Overview: Real-Time Lead Events | DeltaLead

Registering a Webhook Endpoint

Payload Structure

Verifying Webhook Signatures

Responding to Webhooks

Retry Policy

Idempotency

​Registering a Webhook Endpoint

​Payload Structure

​Verifying Webhook Signatures

​Responding to Webhooks

Retry Policy

Idempotency

Registering a Webhook Endpoint

Payload Structure

Verifying Webhook Signatures

Responding to Webhooks