Receive webhooks

​

1. Register an endpoint

{
  "name": "Replies and finished imports",
  "target_url": "https://example.com/hooks/getsales",
  "events": ["messages.received", "data-sources.completed", "workflow-records.completed"]
}

• target_url must be https:// on a public host, and the same URL cannot be registered twice in one workspace (409 duplicate_rejected).
• events[] is an exact list of catalog types, validated one by one; a name outside the catalog is a 422. There is no wildcard: subscribe to the types you handle, and add new ones when you start handling them. The catalog is in section 6.
• filters.account_sid narrows deliveries to one sending identity (a sender profile’s LinkedIn account or mailbox), so an endpoint that serves one sender is not woken by the others.

​

2. Verify deliveries

{
  "webhook_log_sid": "in_wl_Q8rT2vW4xY6z",
  "type": "messages.received",
  "emitted_at": "2026-11-01T09:12:44+00:00",
  "team_sid": "ts_tm_Hx7kQ3mN2pL4",
  "trace_id": "0198f2ab-7c11-7e32-9a41-d2b64f2a91c3",
  "payload": {
    "sid": "ub_ms_Jk2mP9nR4qW1",
    "conversation_sid": "ub_cv_Bv9nK4xP1sD7"
  }
}

import crypto from "node:crypto";

function verify(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.split("=") as [string, string]),
  );
  if (!parts.t || !parts.v1) return false;
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (age > 300) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  const received = Buffer.from(parts.v1);
  const digest = Buffer.from(expected);
  // timingSafeEqual throws on a length mismatch, so check that first.
  return (
    received.length === digest.length && crypto.timingSafeEqual(digest, received)
  );
}

import hashlib, hmac, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    # Parse defensively: a malformed header must return False, not raise.
    parts = dict(kv.split("=", 1) for kv in header.split(",") if "=" in kv)
    if "t" not in parts or "v1" not in parts:
        return False
    try:
        ts = int(parts["t"])
    except ValueError:
        return False
    if abs(time.time() - ts) > 300:
        return False
    expected = hmac.new(
        secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

​

3. Test before relying on it

​

4. Retries and auto-disable

​

5. Use the delivery log

• POST /api/webhook-logs/search lists deliveries with status, response code and timing; filter by webhook, sending identity, event type, status or response code, and include the webhook.
• POST /api/webhook-logs/metrics aggregates outcomes over a required period (from, to): success and failure rates, p50, p95 and p99 latency, total retries, the last success and the last failure; group_by splits them by status, event type, response code, webhook or account. The rates count terminal rows only, so a delivery still on its ladder sits in counts.groups.status.retrying instead.
• POST /api/webhook-logs/{sid}/retry re-arms one delivery: status back to pending, due now, the original envelope to the original URL, retry_count kept (it counts attempts that went out). Refused on an in_progress row (409: cancel it or wait), on a cancelled one (that was a decision) and while the parent webhook is deleted or off (422).
• POST /api/webhook-logs/{sid}/cancel stops a delivery that has not settled, from pending, retrying or in_progress. On an in_progress row the attempt in flight may still land as a success, which wins over the cancel; the answer says so with in_flight_attempt_pending: true, so read the row again.

​

6. The event catalog

​

Rotating the secret