Webhooks

Every change in an org's audit log is an event a webhook can receive: users signing up or failing to sign in, changes to brands, apps and APIs, members joining, and the rest. Webhook events lists every one. Webhooks need a plan that includes them (otherwise plan_feature_unavailable).

SubscribingCopy Anchor Link

Subscribe a URL to events: https, on the public internet, with the events it wants. The answer has its signing secret (whsec_…), in that answer only. A subscription receives the events recorded after it exists, while it's on.

Send a test event (webhook.test) to check your endpoint; the answer says how it took it.

ReceivingCopy Anchor Link

Each delivery is a JSON POST with the event (type, timestamp and data: the audit row) and Standard Webhooks headers: webhook-id, webhook-timestamp and webhook-signature. To check it:

1. Take the raw body, before any parsing.
2. Sign <webhook-id>.<webhook-timestamp>.<body> with HMAC-SHA256, keyed by the secret's base64 part (after whsec_).
3. Compare it, in constant time, with each v1,<signature> in webhook-signature: one matching is enough.
4. Refuse a timestamp more than a few minutes old, and an id you've seen before.

Answer 2xx within 10 seconds. Anything else is tried again, 6 times in all, with growing waits, one delivery at a time per subscription. A webhook's deliveries shows each one's status, attempts, last status code and error.

Rotating the secretCopy Anchor Link

Rotate the signing secret to get a new one, in that answer only. For 24 hours, deliveries carry signatures by both, so your endpoint can switch over without missing any.

When deliveries keep failingCopy Anchor Link

After 5 deliveries in a row fail every attempt, Synq turns the subscription off (disabled_reason says why) and emails the org's owner and admins. Fix the endpoint, then turn it on again.