How to Write Great Webhook Docs

The magic of webhooks lies in their simple yet powerful potential for real-time data exchanges between applications. However, the actual magic doesn't happen without a strong foundation: Great documentation.

Even if your webhook service is perfectly secure, reliable, and scalable, you need great documentation to provide a seamless user experience.

Here are the things you need to include in your webhook docs:

Event Catalog

The event catalog is a well-organized list of all possible events, their associated schemas, and real-world examples. Essentially, the equivalent of good API docs.

Here's an example from Svix:

Along with a comprehensive list, real-world examples help users get a feel for the payload structure. Additional details about event triggers and their uses can help users know when and how to best use each event.

Testing

Your documentation should clearly demonstrate how to trigger test events, preferably with predefined examples that accurately reflect the actual payload structure. That said, avoid permitting custom payloads to minimize potential security risks.

We've seen people get burned on this in the past.

Tools like ngrok or Svix Play can be really useful for testing webhook integrations locally.

Shopify does an amazing job explaining how to configure and test a webhook endpoint: https://shopify.dev/docs/apps/webhooks/configuration/https

Signature Verification

Security is paramount, and verifying webhook signatures is a critical security practice. Your documentation should detail the signature scheme, including how to correctly sign payloads, concatenate necessary data, and generate the signature.

Clear steps on verifying signatures, including dealing with timestamps and framework-specific guidance, are essential. Including code samples for signature verification boosts clarity and supports developers in correctly implementing the process.

A great example of this would be Stripe https://stripe.com/docs/webhooks/signatures.

Error Handling

Expect the unexpected. Proper error handling is a core component of any robust webhook system. Your documentation should set clear expectations on response codes, both for successful and failed webhook deliveries.

Clear recovery instructions, like how to replay failed events or troubleshoot, can equip users to navigate through potential issues effectively.

Endpoint Failures and IP Whitelisting

Endpoint failures are an unfortunate reality that can occur for a myriad of reasons. Your documentation should guide users on how to rerun failed events and manually recover from specific errors.

Also, consider those users with strict firewall rules, and if possible, document the source IP addresses or IP ranges from which your webhooks will be sent to ensure smooth communication.

Retry Schedule

Document the retry schedule explicitly in cases of delivery failures. This should include the intervals between attempts, the maximum retry limit, and any specific rules applied during this process.

We're going to highlight our own docs again because we actually don't see many webhook providers do this. https://docs.svix.com/retries

Transparency about retry mechanisms can help users better understand what to expect during webhook failures.

Conclusion

Good webhook documentation is like a well-written manual; it makes using the product a breeze. Following these simple tips, which we've gathered through our experience building a robust webhook platform, can transform a complex webhook system into an intuitive tool.

For more content like this, make sure to follow us on Twitter, GitHub, or RSS for the latest updates for the Svix webhook service, or join the discussion on our community Slack.

Also published here