Webhooks (Beta)
Webhook event types
Active OutboundSync webhook events sync.failed and sync.recovered, test.ping for endpoint checks, and reserved event names you cannot subscribe to yet.
When to use this guide: You need to know which Sync Monitoring events fire today, when they fire, and which names are reserved. Inbound SEP event types on Sources are separate — this page is for product Webhooks.
Active events (Sync Monitoring)
Section titled “Active events (Sync Monitoring)”| Event | Fires when |
|---|---|
sync.failed |
A source→CRM sync transitions from healthy to failing for that source×connection pair — one alert per incident, not every failed job |
sync.recovered |
A previously failing source→CRM sync starts succeeding again (failing→healthy), on its next successful sync |
test.ping |
Delivered only by POST /api/v1/webhooks/:id/test — not a subscription type |
Empty or omitted enabledEvents on a webhook means all currently active events (sync.failed and sync.recovered). It does not include reserved names or test.ping.
When sync.failed fires
Section titled “When sync.failed fires”How quickly sync.failed fires depends on the kind of error:
- Connection-breaking errors fire on the first failure. A CRM auth error (expired or revoked tokens, app not installed) or a CRM plan or storage limit means every later sync would fail too. OutboundSync fires
sync.failedright away and pauses CRM sync for that source×connection until you reconnect the CRM. - Other failures fire after 3 in a row. Mapping or internal errors need 3 consecutive failed syncs for the same source×connection. A success in between resets the count.
- Temporary errors don’t count. CRM rate limits (429), CRM server errors (5xx), network errors, and expired Salesforce sessions don’t trigger an alert. Only some of them are retried automatically; the rest stay as Error in History. The exception is Salesforce record lock errors that still fail after their automatic retries, which count as failures. Update-only misses and a missing sequencer API key are handled per event and don’t trigger an alert.
Each sync.failed payload carries a readable reason and a remediation with the fix. See Common sync.failed reasons for every category.
Reserved event names
Section titled “Reserved event names”These names are held in the namespace. Subscribing returns 400 with the list of available types. They are not delivered yet:
connection.created,connection.degraded,connection.restored,connection.removedblocklist.entry_added,blocklist.sync_failed,blocklist.sync_recovereddestination.forward_failed,destination.forward_recovered- Provisional record-write names such as
contact.created/company.created(naming may change before they ship)
Do not invent shipping timelines for reserved events.
