Lead Distribution Webhooks: How to Deliver Leads in Real Time

A lead distribution webhook is an HTTP POST request that your distribution platform fires at a buyer's endpoint the instant a lead is matched, scored, and accepted, carrying the full lead payload as a signed JSON body. Instead of buyers polling your API every few seconds for new leads, your platform pushes each lead exactly once, with a cryptographic signature, a unique event ID, and a retry policy if the buyer's server is slow or down. According to Stripe's webhook documentation, the industry pattern is a signed POST with HMAC-SHA256, a timestamp, and a 5 minute tolerance window for replay protection, and Lead Distro AI uses the same model.

This guide is written for engineers who already know what a webhook is. We cover the payload schema, signature verification (with code), retry and idempotency rules, webhook vs polling vs push notifications, and the debugging patterns that catch 90 percent of integration bugs before they hit production. If you are evaluating a lead distribution API, webhooks are the delivery half of that API.

Key Takeaways

• A lead distribution webhook is a signed HTTP POST your platform sends to a buyer's endpoint the moment a lead is accepted, replacing polling with push delivery.
• Production-grade webhooks require HMAC-SHA256 signature verification, a unique event ID for idempotency, and at least 3 days of exponential-backoff retries.
• Standard Webhooks (the open spec at standardwebhooks.com) and Stripe's webhook design are the two reference implementations every lead platform should follow.
• Webhook latency targets are under 500 ms end-to-end (platform accept → buyer 2xx response), since leads contacted within 60 seconds convert at significantly higher rates.
• Polling adds latency, wastes API calls, and is brittle at scale. Use webhooks for delivery and reserve polling for reconciliation only.

What Is a Lead Distribution Webhook?

A lead distribution webhook is an outbound HTTP POST request that a distribution platform fires at a buyer-defined URL the instant a lead is routed to that buyer. The body of the POST is a JSON payload containing the lead's contact data, scoring, and routing metadata. The buyer's server responds with 2xx to acknowledge receipt, or any non-2xx status to trigger a retry.

The defining property of a webhook is that the platform initiates the call. With a REST API, the buyer's server polls the platform every N seconds asking "any new leads?" and pulls them. With a webhook, the platform pushes each lead exactly when it is ready. This eliminates polling latency, reduces API call volume by 95 percent or more in typical lead operations, and gives the buyer real-time delivery on the same critical path as their ads spend.

For agencies running ping-post distribution, webhooks deliver the result of the post phase. The ping uses synchronous API calls so the platform can collect bids in milliseconds. The post uses a webhook so the winning buyer gets the full payload pushed to them without an extra round trip.

Webhook vs Polling vs Push Notifications

The three common patterns for moving leads from a distribution platform to a buyer's system each have a different latency, cost, and failure profile. Choose based on your volume and your buyer's infrastructure.

Webhooks win for lead delivery in almost every modern setup. Polling is appropriate as a backup reconciliation job (for example, a nightly sweep that re-pulls anything the buyer's webhook handler missed). Push notifications are for human alerts on a phone, not for moving structured lead data between servers.

Payload Schema

A production lead distribution webhook payload should include a stable envelope (event metadata) and a typed data object. Here is the schema Lead Distro AI uses:

{
  "id": "evt_01HX9KQR5P8N3M2W7B4Y6Z1A0C",
  "type": "lead.delivered",
  "timestamp": "2026-05-19T14:30:00.123Z",
  "version": "2026-03-01",
  "data": {
    "lead_id": "ld_abc123",
    "buyer_id": "buyer_456",
    "campaign_id": "camp_legal_tx_2026",
    "score": 87,
    "price": 175.00,
    "currency": "USD",
    "contact": {
      "first_name": "Maria",
      "last_name": "Garcia",
      "phone": "+15551234567",
      "email": "maria@example.com",
      "state": "TX",
      "zip": "77001"
    },
    "case": {
      "type": "auto_accident",
      "injury_severity": "moderate",
      "accident_date": "2026-05-15",
      "at_fault": false
    },
    "tracking": {
      "source": "google_ads",
      "ip_address": "203.0.113.42",
      "user_agent": "Mozilla/5.0 ...",
      "consent_timestamp": "2026-05-19T14:29:55Z"
    }
  }
}

A few rules that come from years of webhook design (see the Standard Webhooks spec for the formal version):

• id is a unique event ID. The buyer dedupes against this on receipt.
• type follows resource.action (lead.delivered, lead.returned, lead.converted).
• version is a payload schema version. When you add fields, do not break old buyers.
• timestamp is ISO 8601 with millisecond precision and a Z suffix.
• The data object is the only thing that changes between event types.

Buyers should treat any unknown top-level fields as forward compatibility and ignore them rather than erroring.

Signature Verification (HMAC-SHA256)

Any endpoint on the public internet can receive a POST from anyone. Signature verification is what tells the buyer this POST actually came from your distribution platform and was not modified in transit. The pattern below matches Stripe's Stripe-Signature design and the Standard Webhooks specification.

The platform computes an HMAC-SHA256 over timestamp.payload using a shared secret, and sends it in a header:

X-LeadDistro-Signature: t=1747667400,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Here is a Node.js verifier the buyer would run on every incoming request. It reads the timestamp, recomputes the signature, and compares in constant time:

import crypto from "crypto";
 
export function verifyLeadDistroSignature(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((kv) => kv.split("="))
  );
  const timestamp = parts.t;
  const signature = parts.v1;
 
  if (!timestamp || !signature) {
    throw new Error("Malformed signature header");
  }
 
  // Reject anything older than 5 minutes (replay protection)
  const ageSeconds = Math.floor(Date.now() / 1000) - Number(timestamp);
  if (ageSeconds > 300) {
    throw new Error("Webhook timestamp outside tolerance window");
  }
 
  const signedPayload = `${timestamp}.${rawBody}`;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(signedPayload)
    .digest("hex");
 
  const ok = crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(signature, "hex")
  );
 
  if (!ok) throw new Error("Invalid signature");
  return true;
}

Three details that catch most buyers off guard. First, the verifier must read the raw request body before any JSON parsing, because any whitespace or key-order change will break the HMAC. Second, use crypto.timingSafeEqual, not ===, to prevent timing attacks. Third, enforce a 5 minute timestamp tolerance to block replay attacks where an attacker captures and replays an old signed request.

Retry Policy and Idempotency

Webhooks fail. The buyer's server returns 500, hits a deploy, runs out of database connections, or just times out. A lead distribution platform must retry until it succeeds or gives up cleanly, and the buyer must handle the same event arriving more than once.

Retry policy. Lead Distro AI retries failed webhooks (any non-2xx, or a timeout over 10 seconds) on an exponential backoff: 30 seconds, 2 minutes, 10 minutes, 1 hour, 4 hours, 24 hours, then daily for 3 days total. This matches Stripe's 3-day live mode retry window. After 3 days the event is marked permanently failed and surfaced in the buyer dashboard for manual review.

Idempotency. Because retries happen, the buyer's handler will sometimes receive the same id twice. The buyer must dedupe on the event id, not on the lead data. The standard pattern is a webhook_events_seen table with event_id as the primary key. On receipt:

INSERT INTO webhook_events_seen (event_id, received_at)
VALUES ($1, NOW())
ON CONFLICT (event_id) DO NOTHING
RETURNING event_id;

If the insert returns a row, process the event. If it returns nothing, the event was already processed and the handler should respond 200 OK immediately without doing the work twice. This pattern is described in the Standard Webhooks consumer guide and is non-negotiable for production reliability.

Always respond 2xx before doing heavy work. A buyer's webhook handler should validate the signature, dedupe, queue the lead for processing, and respond 200 OK in under 1 second. Heavy work (CRM writes, SMS dispatch, AI scoring on the buyer side) happens in a background worker reading the queue. Doing the work synchronously in the webhook handler causes timeouts and triggers unnecessary retries.

Common Debugging Patterns

Most webhook integration bugs fall into a small set of patterns. Knowing them shortens the debug loop from days to minutes.

Signature mismatch. 90 percent of the time the buyer parsed the JSON body before verifying. The HMAC is computed over the raw bytes; once you JSON.parse, key ordering or whitespace can change and the signature fails. Capture the raw body before any middleware touches it.

Clock skew. If the buyer's server clock drifts more than 5 minutes from real time, every webhook fails the tolerance check. Run NTP. This is the single most common reason a previously-working integration starts failing after a server migration.

Silent 200s. Some buyers respond 200 OK from a load balancer before the request reaches the handler. The platform thinks delivery succeeded; the buyer's CRM never sees the lead. Always have the actual handler emit a log line per event and reconcile counts against the platform daily.

Retry storms during outages. If a buyer's endpoint goes hard down for an hour, exponential backoff means a burst of retries hits the moment they come back up. Lead Distro AI staggers retries across an event window to soften this, but buyers should also ensure their handler is horizontally scalable behind the same URL.

Duplicate processing on slow handlers. A handler that takes 15 seconds to respond will trigger a retry from the platform (typical 10 second timeout) while still working on the first delivery. Without idempotency, the buyer's CRM ends up with two copies. Always respond 2xx fast, then process in a worker.

For ping-post specifically, similar patterns apply to the post phase. Read how ping post systems work for the bidding side, and duplicate lead detection for what happens before the webhook even fires.

When to Use Webhooks vs the Lead Distribution API

Webhooks and a polling REST API are not either-or. Most production lead operations use both.

Use webhooks for:

• Real-time delivery of new leads to buyer CRMs and dispatch systems
• Event notifications (lead returned, lead converted, lead disputed)
• Triggering buyer-side workflows on lead state changes

Use the REST API for:

• Initial buyer setup (creating buyer accounts, campaigns, caps)
• Backfilling historical leads on a new integration
• Nightly reconciliation against what webhooks claimed to deliver
• Pulling reports, P&L, and analytics

The pattern is push for events, pull for state. Lead Distro AI's interactive product tour walks through both surfaces side by side.

Choosing a Lead Distribution Platform by Webhook Capability

Not all lead distribution platforms ship production-grade webhooks. Use this checklist when evaluating:

A platform missing any of the first four is not safe for high-volume lead distribution. Replay UI and per-event subscriptions are quality-of-life features that matter once you cross 50 buyers on the network.

FAQ

How do I verify a lead distribution webhook signature?

Read the raw request body before any JSON parsing, then compute HMAC-SHA256 over the string timestamp.body using your shared webhook secret. Compare the result against the v1 value in the X-LeadDistro-Signature header using a constant-time comparison like crypto.timingSafeEqual in Node. Reject any request where the timestamp is more than 5 minutes old to prevent replay attacks. This matches the pattern used by Stripe and the Standard Webhooks specification.

What is the retry policy for a failed webhook?

A good lead distribution webhook retries failed deliveries on an exponential backoff over at least 3 days. Lead Distro AI retries at 30 seconds, 2 minutes, 10 minutes, 1 hour, 4 hours, 24 hours, then once a day for 3 days total. Any 2xx response stops retries. After 3 days the event is marked permanently failed and surfaced in the buyer dashboard for manual replay. This matches Stripe's live-mode retry window and is the industry standard.

What latency should I target for webhook delivery?

End-to-end webhook latency from lead accept to the buyer's 2xx response should be under 500 milliseconds in steady state. The buyer's handler itself should respond in under 1 second by validating the signature, deduping the event ID, and queuing the lead for background processing. Heavy work like CRM writes belongs in a worker, not the webhook handler. Faster delivery directly improves lead-to-contact time, which is the strongest lever on conversion rate.

What goes in a lead distribution webhook payload schema?

A production payload has two parts: a stable envelope and a typed data object. The envelope includes a unique event id, a type like lead.delivered, an ISO 8601 timestamp, and a payload schema version. The data object contains the lead itself: contact info, case or product details, scoring, pricing, and tracking metadata. Versioning the payload lets you add fields over time without breaking buyers running older integrations.

Should I use webhooks or polling to receive leads?

Use webhooks for primary lead delivery and reserve polling for nightly reconciliation. Polling adds 1 to 60 seconds of latency per lead, costs 95 percent more API calls than webhooks at typical volumes, and is brittle when lead volume spikes. Webhooks push each lead the moment it is accepted, hit your CRM in milliseconds, and retry automatically on buyer-side failures. A nightly reconciliation poll that re-pulls anything the webhook handler missed is a useful safety net, not a replacement.

Conclusion

A lead distribution webhook is the difference between buyers seeing leads in milliseconds and buyers seeing leads in minutes. The mechanics are not exotic: HMAC-signed POST, unique event ID, retry policy, idempotent handler. The discipline is in getting every detail right, because each one in isolation can drop or duplicate leads in ways that erode buyer trust.

Lead Distro AI ships production-grade webhooks out of the box: signed payloads, versioned schema, 3-day retry, per-event subscriptions, full delivery logs, and a replay UI for stuck events. Read the API documentation for endpoint reference, or start your free trial to send your first signed webhook in under 10 minutes.

For the engineers reading this on a Saturday at 2am: join the PPL community where lead distribution engineers swap webhook horror stories and code reviews.