Webhooks

A webhook sends an event to a URL you choose the moment something happens, so your systems don’t have to keep asking. Manage endpoints under Company Settings → Integrations → Webhooks, or through the API’s /webhooks endpoints.

Adding an endpoint

1. Choose Add Endpoint, enter an https URL on the public internet, and pick the events it should receive (or all of them).
2. Copy the secret. It is shown once and is how you check a delivery came from us.
3. Use Send Test to check your receiver answers.

An account can have up to 25 endpoints.

Checking a delivery came from us

Each event is a POST with a JSON body. Reply with any 2xx to acknowledge it. Every delivery carries:

• Authorization: Bearer <your endpoint secret>
• X-CN-Signature: t=<unix seconds>,v1=<signature>

The signature is an HMAC-SHA256, in hex, of <t>.<raw body>, keyed with your endpoint secret. Work it out over the exact bytes you received, compare in constant time, and reject a delivery whose t is more than 5 minutes old.

After you rotate a secret, the old one keeps signing for 24 hours alongside the new, so the header carries two v1 values. Accept the delivery if either matches.

Retries, duplicates and order

• A delivery that doesn’t get a 2xx is retried 6 times over about 8.6 hours, then marked dead.
• After 20 dead deliveries in a row the endpoint is turned off and your technical contact is emailed. Events are still recorded; turn it back on and replay the dead deliveries from the delivery log to catch up.
• An event can arrive twice, or out of order. Use eventId to ignore repeats and sequence (which counts up per endpoint) to order them.

Event types

Webhook event types lists every event you can subscribe to, by area.

Watches: the same events by email

To have a person emailed rather than a system called, use Watch on an order or service. It sends the same events to the addresses you choose.