Webhooks, retries and dead letters

A webhook tells another system when something happens in Dispatch. You will be able to register an address, pick the events, watch deliveries and recover failed ones.

Before you start #

• Registering, changing, pausing, rotating the secret and deleting a webhook need the owner role. A manager can list deliveries, view failed ones, send them again and run the queue.
• The receiving address uses https. See "Webhook address safety" below.
• You can register up to 20 endpoints.

The events #

• tow.created: a call was taken.
• tow.status: a call changed status.
• invoice.paid: an invoice became fully paid.
• estimate.approved: a customer or staff member approved at least one estimate line.
• enquiry.created: a website request arrived. Choose any of them, or * for all.

Steps #

1. Open Settings, Webhooks and register an endpoint. Give the address, the events and an optional note up to 120 characters.
2. Copy the signing secret. It starts with whsec_ and shows once, here and again only when you replace it.
3. Send a test delivery to check that your receiver answers.
4. Watch Deliveries. A delivery is queued, ok or failed.
5. Pause an endpoint by setting it inactive. Deliveries stop queueing for it. Resume it when ready.
6. Replace the secret with Rotate secret when you suspect it leaked. The old secret stops working at once.

Retries and dead letters #

• A delivery succeeds when your receiver answers with a 2xx status.
• Any other answer, a timeout or a connection error schedules a retry. There are seven attempts in all, with these waits after each failed attempt: 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours.
• A delivery that fails the seventh attempt becomes a dead letter. The endpoint's failures count goes up, and a later success resets it.
• Open Dead letters to read the last error. Choose Send again to queue a delivery afresh. The queue also runs by itself every 15 seconds, and you can run it now.
• Deliveries are written in the same transaction as the event that caused them, so a crash loses none.

Webhook address safety #

Dispatch checks every address, both when you save it and again when it sends:

• https only, on port 443, 8443 or 8080, with no user name or password and at most 500 characters.
• The name resolves once, and every address it resolves to must be a public internet address. Private networks, loopback, link-local, cloud metadata, shared address space, documentation, multicast and reserved ranges are refused, including IPv6 forms that carry an IPv4 address.
• The connection goes to the address that passed the check, with the original name in the Host header and TLS, so the name stays fixed between the check and the send.
• No redirects are followed. Connecting takes at most 4 seconds and the whole call 6 seconds. A payload can be up to 256 KiB, and Dispatch never reads your answer's body.

If something goes wrong #

• "Webhook addresses must start with https.": change the scheme.
• "Use port 443, 8443 or 8080.": move the receiver.
• "The address points inside a private network, which is blocked.": use a public address.
• The message about resolving the host name: check the name in DNS.
• "At most 20 webhook endpoints.": delete one first.
• A dead letter reads "The signing secret is missing. Make a new secret for this endpoint.": rotate the secret. This follows a restore.
• forbidden (403) "Only the owner can manage webhooks.": ask the owner.