Documenting REST APIs is straightforward: developers make a request and get a response. However, webhooks are different; they are asynchronous events sent from your server to the customer's server. Writing clean, developer-friendly webhook documentation requires a highly structured approach.
1. Document the JSON Payload Schema
Clearly list every key in your webhook payload, specifying the data type and whether the field can be null. Provide complete, copy-pasteable JSON examples representing different event types (e.g., email.received, inbox.created).
2. Describe Retries and Throttling
Clearly state what happens if the customer's server is offline. Document your retry schedule (e.g., exponential backoff over 24 hours). Additionally, explain how developers can verify your webhook signatures using HMAC-SHA256 headers, ensuring their endpoints are safe from spoofed requests.