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
2xxonce the event is durably accepted. The body is ignored. 408,429and any5xxare treated as transient: the lead is marked retryable and may be sent again with the sameX-Unstuck-Event-Id. Use that id to deduplicate.401,403and402mark 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
4xxis 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,403or402, or the connection's last 3 pushed leads were all rejected with a final4xx. One rejected lead does not block the connection. Fix the endpoint, then re-check the connection in the app or viaverify-destination-connection.