>unstuck engine

> Webhook destination — receiving and verifying pushes

A Webhook destination pushes every lead that enters an audience to an HTTPS endpoint you own (each lead once — a lead that leaves and re-enters is not sent again), as a signed JSON POST. This page is the receiver contract: what arrives, how to prove it came from Unstuck, and what to answer.

Connect once, keep the secret

When you connect a Webhook destination you give us your endpoint_url (https only). We mint a signing secret and show it exactly once — in the app, or as data.webhook_signing_secret in the API response. We keep the secret to sign with, but we never display it again. If it is lost or exposed, rotate it: in the app, or POST /functions/v1/update-destination-connection with { "id": "<connection id>", "signing_op": "rotate" }. The new secret comes back once in data.webhook_signing_secret and the old one stops being used immediately, so update your verifier first if you cannot tolerate a gap, then re-check the connection (the rotate call itself sends no test event).

Connecting sends a test event to your endpoint immediately (X-Unstuck-Event: test). Your endpoint must answer 2xx to that call or the connection is marked as needing attention.

What arrives

POST <endpoint_url>
Content-Type: application/json
X-Unstuck-Event: lead.add            # or: test
X-Unstuck-Event-Id: <idempotency key> # absent on the test event
X-Unstuck-Signature: <hex HMAC-SHA256 of the raw body>
// X-Unstuck-Event: lead.add
{
  "event": "unstuck.lead.add",
  "eventId": "<same value as X-Unstuck-Event-Id>",
  "sentAt": "2026-09-18T14:10:55.000Z",
  "leadId": "<the lead's id>",
  "audienceId": "<id of the audience this destination is attached to>",
  "lead": {
    "firstName": "…", "lastName": "…", "fullName": "…",
    "email": "…", "personalEmail": null, "phone": null,
    "linkedinUrl": "https://www.linkedin.com/in/…",
    "jobTitle": "…", "country": "…", "city": null,
    "companyName": "…", "companyDomain": "…",
    "icpCode": "…", "icpScore": 10, "personaCode": null, "personaScore": null,
    "engagementScore": 10, "engagementStage": "warm",
    "signalSource": "…", "signalKeyword": "…", "audienceName": "…"
  }
}

// X-Unstuck-Event: test
{ "event": "unstuck.test", "sentAt": "2026-09-18T14:10:55.000Z" }

Every lead key is always present; a value we do not hold is null, never omitted. signalSource names the signal that brought the lead in (for a keyword signal, the LinkedIn post); signalKeyword (since 2026-11-05) is the keyword that signal matched — one post can match several of your keywords, so the post alone does not tell you which. It is null for a signal with no keyword (a CSV upload, a webhook). If the destination carries field_overrides, the lead object is reshaped to the keys you mapped instead of this default set.

leadId and audienceId (since 2026-10-30) sit beside eventId on every lead.add event, whatever your field mapping: use them to send replies and outcomes back to the right lead. audienceId is the audience this destination belongs to, which can differ from lead.audienceName (the lead's current best audience); it is null only if we could not read it at send time.

Verify the signature

X-Unstuck-Signature is the lowercase hex HMAC-SHA256 of the raw request body bytes using your signing secret. Compute it over the body exactly as received — before any JSON parsing or re-serialisation — and compare in constant time.

Node (any framework that exposes the raw body):

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyUnstuck(rawBody, signatureHeader, secret) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(signatureHeader ?? "", "utf8");
  return a.length === b.length && timingSafeEqual(a, b);
}

Python:

import hmac, hashlib

def verify_unstuck(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

Reject anything that does not verify. The test event is signed the same way with the same secret, so the connect call doubles as a check of your verifier.

What to answer

  • Answer 2xx once the event is durably accepted. The body is ignored.
  • 408, 429 and any 5xx are treated as transient: the lead is marked retryable and may be sent again with the same X-Unstuck-Event-Id. Use that id to deduplicate.
  • 401, 403 and 402 mark the whole connection as needing attention, since they read as "you no longer accept us" (or the account is inactive): the run stops, and the lead is kept and sent again once you fix the endpoint and the connection is re-checked.
  • Any other 4xx is final for that lead: it is recorded as rejected and not re-sent.
  • Requests time out after 20 seconds; answer fast and process asynchronously.

Where to look when something is off

  • The destination's run history (list-destination-runs) lists runs, not single pushes: each run's status, its counts (delivered, skipped, failed) and our error message. The HTTP status your endpoint returned for each request is in your own server logs.
  • A connection marked needs attention means your endpoint answered 401, 403 or 402, or the connection's last 3 pushed leads were all rejected with a final 4xx. One rejected lead does not block the connection. Fix the endpoint, then re-check the connection in the app or via verify-destination-connection.