10 webhook best practices

As a receiver

1. Answer within seconds

Validate, queue, answer 2xx. Everything slow happens afterwards. Timeouts are the number one cause of “phantom” retries.

2. Be idempotent

Deduplicate by event ID – the same event will arrive twice. The pattern.

3. Verify signatures

Over the raw body, with a timing-safe comparison, including a timestamp check. Details.

4. Return honest status codes

5xx when you want a retry, 2xx when you don't. The table.

5. Log every delivery

Headers, body, your response, timestamp. When something goes missing in three weeks, this log is the only thing that answers “did it even arrive?”.

6. Access the payload defensively

Optional fields disappear, new ones appear. Never assume a fixed shape. Payload guide.

7. Plan for the endpoint being down

Providers retry for a while and then stop – sometimes disabling the endpoint. Know your provider's window, and check for missed events after an outage.

As a sender

8. Retry with exponential backoff

Seconds, minutes, hours – not every second. And stop eventually, with a notification to the endpoint's owner.

9. Sign your payloads and include a timestamp

Give receivers a way to trust you, and make replay attacks detectable.

10. Keep payloads small and stable

Send IDs and the essentials; let receivers fetch details via API. Add fields, don't rename them – renames break every receiver at once.

The meta-rule

Match effort to consequences. A webhook that provisions accounts deserves all ten rules. A webhook that makes your phone buzz when a build fails deserves a long random URL and a fast answer – and that's genuinely fine. Overengineering notification plumbing is its own kind of mistake.

Start here if the topic is new: what is a webhook.

Get Webhooky

Free for your first 100 notifications – set up your endpoint in two minutes.