Why it matters
A webhook makes your product part of another system’s workflow. The contract includes event meaning, authentication, retry behavior and a way to investigate failed deliveries.
A webhook is an API in reverse: customers depend on your events to keep their systems in sync. Deliveries will fail and arrive more than once, so the event contract and retry story matter.
Decisions to make
- Pick stable event names and payload versions.
- Define retry windows and dead-letter behavior.
- Let customers rotate signing secrets and replay deliveries.
- Choose event names and payload versioning before integrations depend on them.
- Define retry duration, replay access and endpoint verification.
Build checklist
- Sign each delivery and include a unique event ID.
- Document at-least-once delivery and ordering behavior.
- Give administrators delivery history with response status and retry controls.
- Sign payloads and document signature verification.
- Expose delivery attempts, response codes and manual replay.
Common mistakes
- Making the customer endpoint part of your own write transaction.
- Sending an event before its transaction is committed.
- Assuming a customer endpoint will respond quickly or only once.
Tools & references
4 starting points to compare or study. Check fit, maintenance, terms and current capabilities before choosing one.
