Receive webhooks

​

1. Register an endpoint

{
  "name": "Mass action outcomes",
  "target_url": "https://example.com/hooks/gtm",
  "events": ["mass-actions.settled", "mass-actions.paused"]
}

• name is required (1 to 255 characters). Omitting it fails validation.
• target_url must be https:// and must not resolve to a loopback, private or link-local address. DNS names are resolved and checked too, not just IP literals.
• Each events[] value is validated against the platform event catalog, which currently carries 94 types across the services.
• The same target_url cannot be registered twice in one team.
• events: ["*"] subscribes to the entire catalog, including event types added later.

​

Filter what you receive

• filters.account_sid restricts deliveries to one account (ln_ac_... for LinkedIn, em_ac_... for email). The sid is matched verbatim, so channels added later work here without a change.
• filters.where takes a small filter expression over the event payload. It is validated strictly at write time: nesting depth is capped at 5 and the whole expression at 20 leaf conditions, answering filter_grammar_invalid or filter_leaves_limit_exceeded when it exceeds either.

​

2. Verify deliveries

{
  "webhook_log_sid": "wh_lg_...",
  "type": "mass-actions.settled",
  "emitted_at": "2026-08-13T09:12:44Z",
  "occurred_at": "2026-08-13T09:12:41Z",
  "team_sid": "ts_tm_...",
  "trace_id": "019ffa3d-...",
  "payload": {}
}

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 or event type.
• POST /api/webhook-logs/{sid}/retry re-sends. Allowed from pending, retrying, failed and success (a manual re-send of a delivered event is legitimate), and only while the parent subscription is still live: a deleted or off webhook rejects the retry.
• POST /api/webhook-logs/{sid}/cancel stops a delivery that has not settled. Allowed from pending, retrying and in_progress.
• POST /api/webhook-logs/metrics aggregates outcomes. period with from and to is required and may span at most 90 days.

​

Rotating the secret