Webhooks

Webhooks push events from the CRM to your HTTPS endpoint as they happen, so you don't have to poll. Deliveries are signed, retried, and logged.

Create an endpoint

Register an endpoint with the event types it wants (in the app under Settings → Webhooks, or with the Webhooks endpoints in the API reference). The response includes the signing secret (whsec_…) once. Store it next to your API key.

Event types

Subscribe to exact types, or to a prefix with *:

PatternMatches
record.*record.created, record.updated, record.deleted
email.*email.sent, email.opened, email.clicked, email.unsubscribed
segment.entered, segment.exitedA record joined or left a segment
automation.*automation.run_completed, automation.run_failed
import.completedAn import job finished

Payload

Every delivery is a JSON POST with the same envelope:

JSON
{
"id": "8f3c2a1e-6b4d-4e7a-9c0f-1d2e3f4a5b6c",
"version": 1,
"event": "record.updated",
"occurredAt": "2026-09-25T10:15:30Z",
"data": {
"objectKey": "contact",
"recordId": "5b1c2f6e-8d3a-4c1e-9f0b-2a7d6e4c8b19",
"changedFields": ["phone", "locale"]
}
}
  • id is unique per event and stays the same when a delivery is retried or redelivered, so deduplicate on it.
  • version is the envelope format. It only changes for a breaking change, announced in advance.
  • record.created and record.updated list the field keys the write set or changed in changedFields; fetch the record for the values.

Respond with any 2xx status within a few seconds. Do slow work asynchronously after acknowledging.

Verify the signature

Each request carries these headers:

HeaderContent
X-Crm-EventThe event type
X-Crm-TimestampUnix time (seconds) when it was sent
X-Crm-SignatureLowercase hex HMAC-SHA256(secret, timestamp + "." + rawBody)
X-Crm-Delivery-IdThe same on every attempt of one delivery. A delivery can arrive more than once, so skip an id you have already processed. Record the id once your work is done, not on arrival, and note that Redeliver in Settings → Webhooks sends a delivery again with its id.

To verify a delivery:

  1. Read the raw request body, before any JSON parsing.
  2. Compute HMAC-SHA256 over timestamp + "." + rawBody with your secret.
  3. Compare with X-Crm-Signature in constant time.
  4. Reject timestamps older than 5 minutes to prevent replays.

Check a webhook's signature has a worked example to test your code against, and samples for Node.js, Python, PHP and C#. Use Send a test on the endpoint in Settings → Webhooks to send a signed webhook.test event whenever you like.

const crypto = require('node:crypto')
function verify(headers, rawBody, secret) {
const ts = headers['x-crm-timestamp']
const expected = crypto.createHmac('sha256', secret)
.update(`${ts}.${rawBody}`).digest('hex')
const given = headers['x-crm-signature'] ?? ''
return given.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(given))
&& Math.abs(Date.now() / 1000 - Number(ts)) < 300
}

Retries and delivery guarantees

Deliveries are at least once. A failed delivery (a non-2xx status, a timeout or a connection error) is retried with exponential backoff: 8 attempts, starting after 30 seconds and doubling each time. After the last attempt it is marked dead and can be redelivered from the delivery log.

Because a delivery can arrive more than once, make your handler idempotent: remember the ids you have already processed and skip a repeat.