Webhooks
A webhook subscription sends a signed POST to your HTTPS endpoint when an event you chose happens in your organization.
Manage subscriptions
Section titled “Manage subscriptions”All routes live under /api/v1/webhooks and need the settings.webhooks permissions shown. Creating a subscription, listing deliveries and replaying a delivery also need a plan that includes webhooks (otherwise 402).
| Method and path | Does | Permission |
|---|---|---|
GET /api/v1/webhooks |
List subscriptions | settings.webhooks.view_global |
POST /api/v1/webhooks |
Create a subscription | settings.webhooks.create |
GET /api/v1/webhooks/{id} |
Get one subscription | settings.webhooks.view_global |
PUT /api/v1/webhooks/{id} |
Update url, events, secret or is_active |
settings.webhooks.edit |
DELETE /api/v1/webhooks/{id} |
Delete a subscription | settings.webhooks.delete |
POST /api/v1/webhooks/test/{id} |
Send a test delivery now | settings.webhooks.edit |
GET /api/v1/webhooks/{id}/deliveries |
Delivery log (status, page, limit) |
settings.webhooks.view_own |
POST /api/v1/webhooks/deliveries/{deliveryId}/replay |
Send a past delivery again | settings.webhooks.edit |
curl -X POST "https://api.pitch2sale.com/api/v1/webhooks" \ -H "Authorization: Bearer pat_…" \ -H "Content-Type: application/json" \ -d '{ "name": "Data warehouse", "url": "https://hooks.example.com/pitch2sale", "events": ["lead.created", "opportunity.won"], "secret": "<random string, at least 16 characters>" }'name is required by validation but not currently stored. url must use https://, events needs at least one event, and is_active defaults to true.
Events
Section titled “Events”| Area | Events |
|---|---|
| Leads | lead.created, lead.updated, lead.deleted, lead.status_changed |
| Contacts | contact.created, contact.updated, contact.deleted |
| Opportunities | opportunity.created, opportunity.updated, opportunity.won, opportunity.lost |
| Activities and tasks | activity.created, task.created, task.completed, call.completed |
| Email and SMS | email.received, email.sent, sms.received, sms.sent |
| Forms | form.submitted |
| Proposals and contracts | proposal.sent, proposal.accepted, proposal.declined, contract.signed |
| Invoices | invoice.created, invoice.sent, invoice.paid, invoice.overdue |
| Workflows | workflow.triggered |
An unknown event name is rejected with 400. The test endpoint sends the event webhook.test.
The request you receive
Section titled “The request you receive”POST /pitch2sale HTTP/1.1Content-Type: application/jsonUser-Agent: CRM-Webhook/1.0X-CRM-Event: lead.createdX-CRM-Signature: t=1759829400,v1=<64 lowercase hex characters>X-CRM-Timestamp: 1759829400X-CRM-Delivery-Id: <delivery id>
{"event":"lead.created","org_id":"…","timestamp":"2026-10-07T09:30:00.000Z","data":{ … }}| Field | Meaning |
|---|---|
event |
The event name (also in the X-CRM-Event header). |
org_id |
Your organization’s id. |
timestamp |
ISO 8601 time this attempt was sent; retries and replays get a new one. |
data |
The record or change that triggered the event. |
Headers: X-CRM-Signature carries the signature and the time it was made (t=<unix seconds>,v1=<hex>); X-CRM-Timestamp repeats t; X-CRM-Delivery-Id identifies this delivery attempt; each retry and each replay gets its own id, so use it to log attempts and drop an exact duplicate, and use the record’s own id and updated_at in data to decide whether a change is new.
Verify the signature
Section titled “Verify the signature”v1 is the lowercase hex HMAC-SHA256, keyed with the subscription secret, of the string <t>.<raw body>: the t value from the header, a dot, then the exact request bytes before any JSON parsing. Verify in three steps: parse t and v1 from the header, recompute the MAC over t + '.' + rawBody and compare in constant time, then refuse the request if t is more than 5 minutes from your clock. The timestamp is inside the signed string, so a captured delivery cannot be replayed later with a fresh timestamp.
import { createHmac, timingSafeEqual } from 'node:crypto';const TOLERANCE_SECONDS = 300;export function verify(rawBody, header, secret, nowSeconds = Math.floor(Date.now() / 1000)) { const parts = Object.fromEntries((header ?? '').split(',').map((kv) => kv.split('='))); const t = Number(parts.t); if (!Number.isFinite(t) || !parts.v1) return false; const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`, 'utf8').digest('hex'); const a = Buffer.from(parts.v1, 'utf8'), b = Buffer.from(expected, 'utf8'); if (a.length !== b.length || !timingSafeEqual(a, b)) return false; return Math.abs(nowSeconds - t) <= TOLERANCE_SECONDS;}In Express, read the body with express.raw({ type: 'application/json' }) on the webhook route so rawBody is the original bytes. Reject the request with 401 when verify returns false.
For one release, deliveries also carry X-CRM-Signature-Legacy: the old scheme, a plain hex HMAC-SHA256 of the raw body with no timestamp. Receivers that still check it keep working, but move to X-CRM-Signature with the timestamp check, because the legacy header does not protect against replay and will be removed.
Responses, retries and timeouts
Section titled “Responses, retries and timeouts”- Answer with any
2xxstatus within 15 seconds. Do slow work after you respond. - Any other status, a timeout or a network error counts as a failure. Redirects are not followed: a
3xxis a failure. - A failed delivery is retried up to 6 attempts in total. The retries wait 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours after the previous failure, so an outage of about 14 hours is covered.
- Every attempt is recorded in the delivery log; replay a delivery with
POST /api/v1/webhooks/deliveries/{deliveryId}/replay. - After 10 deliveries in a row have exhausted their retries, the endpoint is switched off automatically (
is_active: false,disabled_reason: "auto_failures"). The endpoint’s creator gets a notification and awebhook.auto_disabledentry appears in the audit log. Fix the receiver, then re-enable the endpoint withPUT /api/v1/webhooks/{id}and{"is_active": true}or the toggle in Settings → Webhooks; the failure counter resets on the next successful delivery. - Deliveries can arrive more than once and out of order. Make your handler idempotent.
timestampis when this attempt was sent; retries and replays get a new one. To order changes, compare the record’s ownupdated_atindata.