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 *:
| Pattern | Matches |
|---|---|
record.* | record.created, record.updated, record.deleted |
email.* | email.sent, email.opened, email.clicked, email.unsubscribed |
segment.entered, segment.exited | A record joined or left a segment |
automation.* | automation.run_completed, automation.run_failed |
import.completed | An import job finished |
Payload
Every delivery is a JSON POST with the same envelope:
{"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"]}}
idis unique per event and stays the same when a delivery is retried or redelivered, so deduplicate on it.versionis the envelope format. It only changes for a breaking change, announced in advance.record.createdandrecord.updatedlist the field keys the write set or changed inchangedFields; 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:
| Header | Content |
|---|---|
X-Crm-Event | The event type |
X-Crm-Timestamp | Unix time (seconds) when it was sent |
X-Crm-Signature | Lowercase hex HMAC-SHA256(secret, timestamp + "." + rawBody) |
X-Crm-Delivery-Id | The 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:
- Read the raw request body, before any JSON parsing.
- Compute HMAC-SHA256 over
timestamp + "." + rawBodywith your secret. - Compare with
X-Crm-Signaturein constant time. - 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.