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 105 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). 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

POST /api/webhooks/{sid}/replay
{
  "from": "2026-09-04T16:00:00Z"
}

​

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 every state but in_progress: pending, retrying, failed, success (a manual re-send of a delivered event is legitimate) and cancelled, whatever cancelled it. It re-arms the row without counting as an attempt, so retry_count stays the number of attempts that actually went out (at most 5). 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.

​

6. Read the payload

• client_reference on linkedin-connection-requests.sent, .accepted, .withdrawn, .expired-detected and on linkedin-messages.sent echoes the client_reference you passed to the send. Match on it instead of on a LinkedIn identifier. It is null on rows the sync picked up from LinkedIn’s own UI. Every send verb accepts it: send_linkedin_connection_request and all six message sends (the basic message, voice, InMail, Sales Navigator, Recruiter and the group opener), and the comment, post and repost verbs, which emit no event of their own. A mass-action plan step’s args.client_reference T reaches every row the run creates as T:{item sid}:{step id}, so match the T: prefix.
• counterpart on linkedin-conversations.created, linkedin-messages.received and linkedin-messages.sent is the other side of the thread: { "full_name", "headline", "picture_url" }, or null when we hold no participant data for the thread yet. picture_url is LinkedIn’s signed CDN link and expires within hours, so render it on arrival rather than storing it.
• created_by, where the row has one, is a reference to the actor: { "actor_type", "actor_sid", "actor_name", "oauth_client_sid", "reason" }. actor_name and oauth_client_sid name the OAuth client that acted (an MCP client such as Claude, or n8n) and are null for a user, an API key or a system job. reason is set on system jobs, for example snapshot_capture_job.
• nickname, the profile’s vanity URL slug, is present only where LinkedIn exposes it: the connections list and received invitations. Followers, conversations, messages and sent invitations name people by hash id, so those rows carry nickname only once the same person is also a 1st-degree connection of the account. Match on ln_member_id (stable) or ln_id (the ACoAA... profile id, present on every event) rather than on the slug.
• linkedin-account-activity-log.task-failed fires once for each call an account dispatched that ended failed. Its payload is the activity-log row (sid, linkedin_account_sid, action_type, error_message, duration_ms, created_at, updated_at, trace_id) with pending_age_seconds, how long the call was pending, and failure_source, what failed it: plugin (the call’s own answer), reconcile (nobody finished the call in time) or browser_deleted (its browser was deleted while it ran). On a send’s row, send_outcome and send_outcome_reason say what came of the send, and they are null on every other action. not_sent (refused) means nothing reached LinkedIn. unknown (answer_lost) means the send may be out: a failed call is not a send that did not go out, so ask check-sent before you send it again (Sending once). To receive only the sends in doubt, subscribe with "filters": {"where": {"field": "payload.send_outcome", "op": {"eq": "unknown"}}}.
• deleted_at on a terminal linkedin-connection-requests.* event (accepted, withdrawn, expired-detected) is the moment we detected the transition, not LinkedIn’s own timestamp of it. Acceptance is detected by the next sync of the account’s pending invitations, so it can trail the real acceptance by up to the sync interval. removal_kind says which transition it was.

​

Rotating the secret