Skip to main content

Documenting Your Webhooks

Once you're ready to release your webhook feature, you'll need to add documentation. At Svix we consider our documentation as part of the product. We put a lot of effort into making sure our documentation makes it as easy as possible for our customers to send webhooks reliably at scale. By extension, this includes helping our customers write great docs too.

We've reviewed several webhook services (e.g. Zoom, GitHub, Cloudinary) in a blog series if you're interested in seeing some examples. We also provide a documentation generator at https://dashboard.svix.com/documentation/generator.

Aside from the basics of how to create a webhook, the best webhook docs we see do 5 things well:

  1. Explain why and how to verify webhook signatures (with code samples!).
  2. Provide a comprehensive Event Catalog with detailed explanations and sample payloads of each event type.
  3. Fully explain their retry policy including which status codes will trigger retries, and the actual retry schedule.
  4. Give general troubleshooting tips for initial setup and recovering from endpoint failures.
  5. Give guidance on how to test endpoints.

These 5 things will help your customers get setup without a hassle as well as quickly recover from endpoint failures.

We've also created a lot of tools and content to help you write great webhook docs. Many customers simply link to these materials while others use them as a starting point and customize to their specific use cases: