Operational Experience
Documentation
Delightful developer and ops experience starts with docs that are easy to understand, complete, and insightful. Given each webhook implementation's uniqueness, good documentation is crucial for building webhook consumers fast and safely. Great webhook documentation provides:
| Best Practice | Examples |
|---|---|
| An overview of when webhooks should be used | |
| A list of events supported and how to subscribe to events | |
| (If one time verification check exists), how to perform the verification | |
| A comprehensive list of the security features and why they exist | |
| Human-friendly descriptions of why and how security controls work | |
| The journey (steps) for receiving, validating, and processing webhook events | |
| Example payloads | |
| Complete sample code | |
| How to operate and & retry when webhook messages are lost (i.e. due to outages) | |
| Information that can enable compensatory controls, such as list of IPs for firewall rules |
Unfortunately, we found webhook documentation that makes knowledge assumptions, skips steps, and consistently delivers incomplete code snippets. About 10% of the webhooks we've seen missed critical information in their docs — including lack of the encoding format (base64 or hex), the signature date format (Unix or RFC 3339), and hash signature payload instructions. To overcome incomplete docs, we spent significant time performing guesswork, scraping the internet, and unit testing webhooks until we found something that worked. While we were motivated to continue digging and researching to get the correct answer, many developers would have skipped verifying webhooks out of frustration.