Webhooks
Setup
Account webhooks post a signed JSON request to your URL when something happens in the CRM, such as a new lead or a lead texting back. Set them up in Settings → API → Webhooks.
- Owners and admins add, change and remove webhooks.
- An account can have up to 5 webhooks, each with its own URL and its own events.
- The URL must start with
https://, point to a public internet address and carry no username or password. - Each webhook has its own signing secret. It is shown once, when the webhook is created or its secret is rotated. Rotate makes a new secret and the old one stops working.
- Send test posts a
crm.testdelivery withlead: nullto check your endpoint and signature.
Account event delivery requires Playbooks to be enabled for the business. Events recorded while disabled are not subsequently replayed. Send test can succeed independently of event production. Agent Desk lead events are not emitted.
Events
Pick the events each webhook receives. The event id is in event.id and in the x-syntropic-event header as crm.<event>.
| Event | When | Extra fields |
|---|---|---|
lead.created | New lead | None |
lead.replied.text | Lead replies by text | event.channel is "text"; the body carries a text block |
lead.replied.email | Lead replies by email | event.channel is "email" |
lead.stage_entered | Lead enters a stage | None |
lead.stage_left | Lead leaves a stage | None |
lead.call_outcome | Call outcome picked | None |
lead.no_activity | Time without activity | None |
lead.tag_added | Tag added | None |
lead.field_changed | Field changes | None |
task.completed | Task completed | None |
appointment.set | Appointment set | None |
transaction.created | New transaction | None |
dispo.created | New disposition | None |
rental.closed | Rental closes | None |
deal.under_contract | Deal goes under contract | event.status is "under_contract" |
deal.closed | Deal closes | event.status is "closed" |
buyer.matched | Buyer matches a deal | None |
Payload
Every delivery is a JSON object with these fields:
schema_version,type(crm.event, orcrm.testfor Send test),delivery_id(the same on every attempt of one delivery),attempt(1, 2, …),sent_atandoccurred_at(Unix milliseconds) andaccount_id.event:idandoccurred_at, pluschannelon replies andstatuson deal events.lead: the lead the event is about, read when the delivery is sent:id,name,company,phone,email,address,stage,source,rep_id,created_at,deal_valueandfields(custom field values by key, each with itslabelandvalue). It is{ id }only when the lead was deleted, moved to Trash or sent to the Agent Desk, andnullfor events with no lead.text(lead.replied.textonly): the reply itself, read when the delivery is sent.id,body(the first 5,000 characters),body_truncated(trueonly when the body was cut),from(the number that texted, which can differ fromlead.phone),to(your CRM line, ornull),received_atandmedia_count(the number of media items the carrier reported with the text, which can include layout parts, ornullwhen unknown).textisnullwhen the text was deleted, no longer belongs to this lead, the lead is deleted, in Trash or sent to the Agent Desk, the text is private to an Agent Desk, or the person who replied is linked to an Agent Desk client's lead or that check couldn't finish. The delivery still goes.- The payload never carries attachment links. Read the attachments and the rest of the conversation with text-thread in the REST reference.
A full lead.replied.text delivery:
{
"schema_version": 1,
"type": "crm.event",
"delivery_id": "acwh:delivery_123",
"attempt": 1,
"sent_at": 1793977202000,
"occurred_at": 1793977200000,
"account_id": "account_123",
"event": {
"id": "lead.replied.text",
"occurred_at": 1793977200000,
"channel": "text"
},
"lead": {
"id": "lead_123",
"name": "Sam Seller",
"company": "",
"phone": "(555) 123-4567",
"email": "sam@example.com",
"address": "12 Oak St, Springfield, IL 62701",
"stage": "new",
"source": "Website",
"rep_id": "rep_123",
"created_at": 1793890800000,
"deal_value": 25000,
"fields": {
"cust_gclid": {
"label": "GCLID",
"value": "EAIaIQ"
}
}
},
"text": {
"id": "text_123",
"body": "Yes, still selling. Can you call me after 5?",
"body_truncated": false,
"from": "+15551234567",
"to": "+15559876543",
"received_at": 1793977200000,
"media_count": 1
}
}Signature
Each request carries three headers:
x-syntropic-signature:t=<unix seconds>,v1=<hex>, wherev1is the HMAC-SHA256 of`${t}.${rawBody}`, keyed with the whole webhook secret.x-syntropic-delivery: the delivery id, the same on every attempt.x-syntropic-event:crm.<event>, for examplecrm.lead.replied.text.
Check the signature on the raw request body, before parsing it:
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifySyntropicWebhook(rawBody, signatureHeader, secret) {
if (typeof signatureHeader !== "string") return false;
const parts = Object.fromEntries(
signatureHeader.split(",").map((part) => part.split("=", 2)),
);
const expected = createHmac("sha256", secret)
.update(`${parts.t}.${rawBody}`)
.digest("hex");
const given = Buffer.from(parts.v1 ?? "", "hex");
const wanted = Buffer.from(expected, "hex");
return given.length === wanted.length && timingSafeEqual(given, wanted);
}
app.post("/syntropic", express.raw({ type: "application/json" }), (req, res) => {
const raw = req.body.toString("utf8");
if (!verifySyntropicWebhook(raw, req.get("x-syntropic-signature"), process.env.SYNTROPIC_WEBHOOK_SECRET)) {
return res.sendStatus(401);
}
handleDelivery(JSON.parse(raw));
res.sendStatus(200);
});Retries
- A 2xx answer means the delivery succeeded.
- Non-2xx responses below 500 are permanent failures except 408 and 429. That includes redirects such as HTTP 302: redirects are not followed.
- HTTP 408 and 429, 5xx answers, timeouts (10 s) and transient transport failures are retried after 1 minute, then 15 minutes, for 3 attempts in all. A delivery expires 30 days after it was queued.
- At most 10 deliveries are claimed per account during one drain invocation. There is no global concurrency promise.
- Account send blocks cancel the delivery. Cancelled deliveries do not resume automatically.
- Desk send restrictions and pending reply holds keep the delivery pending until it is eligible or expires.
- Delivery is at least once: dedupe on
x-syntropic-delivery.
Delivery log
Each webhook in Settings → API → Webhooks shows its last 50 deliveries: status, attempts, HTTP status, error and sent time. The log never shows the request body.