Developers

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.test delivery with lead: null to check your endpoint and signature.
Before you rely on it

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

EventWhenExtra fields
lead.createdNew leadNone
lead.replied.textLead replies by textevent.channel is "text"; the body carries a text block
lead.replied.emailLead replies by emailevent.channel is "email"
lead.stage_enteredLead enters a stageNone
lead.stage_leftLead leaves a stageNone
lead.call_outcomeCall outcome pickedNone
lead.no_activityTime without activityNone
lead.tag_addedTag addedNone
lead.field_changedField changesNone
task.completedTask completedNone
appointment.setAppointment setNone
transaction.createdNew transactionNone
dispo.createdNew dispositionNone
rental.closedRental closesNone
deal.under_contractDeal goes under contractevent.status is "under_contract"
deal.closedDeal closesevent.status is "closed"
buyer.matchedBuyer matches a dealNone

Payload

Every delivery is a JSON object with these fields:

  • schema_version, type (crm.event, or crm.test for Send test), delivery_id (the same on every attempt of one delivery), attempt (1, 2, …), sent_at and occurred_at (Unix milliseconds) and account_id.
  • event: id and occurred_at, plus channel on replies and status on 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_value and fields (custom field values by key, each with its label and value). It is { id } only when the lead was deleted, moved to Trash or sent to the Agent Desk, and null for events with no lead.
  • text (lead.replied.text only): the reply itself, read when the delivery is sent.
    • id, body (the first 5,000 characters), body_truncated (true only when the body was cut), from (the number that texted, which can differ from lead.phone), to (your CRM line, or null), received_at and media_count (the number of media items the carrier reported with the text, which can include layout parts, or null when unknown).
    • text is null when 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>, where v1 is 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 example crm.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.

Webhooks | Syntropic Developers