Stripe Webhook Documentation Review

This post is a part of our "Documentation Review" series, where we collaborate with different companies to review, analyze and improve their docs. You can find the rest of the posts in the series here.

As the webhook as a service provider to companies like Brex, Benchling, and Lob, we obsess over our documentation and have read a lot of webhook documentation.

Stripe is a financial services company that is building the financial infrastructure for the internet. Millions of companies of all sizes use Stripe online and in person to accept payments, send payouts, automate financial processes, and ultimately grow revenue.

The best documentation we've seen generally has these five elements: (1) signature verification, (2) event catalog, (3) retry policy, (4) troubleshooting and failure recovery, and (5) testing tools.

TL;DR:
Signature Verification: A+
Event Catalog: A-
Retry Policy: A-
Troubleshooting and Failure Recovery: A
Testing Tools: A

Signature Verification

Signature Verification is a critical security feature of webhooks. It lets users verify that a webhook was actually sent from the expected source.

Stripe offers one of the best user experiences for webhook signature verification by offering official libraries. Verifying signatures is one of the most common issues people run into when setting up webhook endpoints because you need to be exact with what inputs you're using to construct the signature. Providing an official library with methods for verifying signatures makes this tricky step trivial.

Stripe also outlines how to verify signatures manually in the case that you wish to build your own custom solution. They explain how to extract the timestamp and signatures from the header to create the signed payload as well as how to compute the HMAC using SHA256. They even have a callout to use a constant time string comparison to guard against timing attacks.

Overall, we really can't find anything we'd change about this section. There is even a section about preventing replay attacks using the timestamp.

Grade: A+

Event Catalog

The Event Catalog documents the event types users can subscribe to. They denote the type of message being sent and are the primary way for webhook consumers to configure what events they are interested in receiving. The best event catalogs list every available event type with sample payload schemas and description of what actions trigger the event.

Stripe has a comprehensive event catalog that lists every available event type with a description of when the event is triggered. We generally like to see sample payloads for each event type. Stripe provides a sample payload in the section that describes the event object but explicitly states that the data object will be different for each event type so it would be nice to have samples for each event type. We did end up finding a schema for each event object but it would be nice to at least have a link directly in the list of event types if not full payload samples.

Grade: A-

Retry Policy

Retries help make webhook systems more reliable. Endpoints can fail intermittently so retrying failed messages automatically avoids users losing important notifications.

Stripe has an entire section for event delivery behaviors where they describe the retry mechanism. Messages are attempted for 3 days on an exponential backoff schedule. They also let you test a more limited automatic retry schedule in test mode along with offering manual retries of specific events. This massively improves the experience of troubleshooting and debugging failing endpoints.

The only thing we'd like to see is the actual retry schedule in the documentation. There is a link to the Events section of the Stripe dashboard that will show the timing of the next retry but we think it's very useful for developers to understand the full schedule.

Grade: A-

Troubleshooting and Failure Recovery

A bit of a theme but once again, Stripe dedicates a section in their docs to troubleshooting and debugging webhooks. They start with a few common issues that users might run into, then provide some links to the webhooks and events tabs in the Stripe dashboard so that users can examine the failures.

We also really liked their table of webhook statuses, what they mean, and how to approach fixing the issue. This really makes developers' lives much easier when debugging webhooks because they get a massive head start on understanding the issues they're dealing with.

Grade: A

Testing Tools

Stripe has an entire section dedicated to testing. They address two common testing suggestions by explaining how to send test events to localhost using their CLI. These are generally separate suggestions because most people don't offer a CLI and end up building a separate test event sender and then suggesting ngrok for tunneling.

The most common testing suggestion we see is to use a request interceptor tool like Svix Play that spins up a public endpoint URL that you can send webhooks to and examine the payload and headers. This helps users try out the webhooks very quickly and without needing to build their own endpoint to receive the webhook. We'd love to see a similar suggestion from Stripe.

Grade: A

Summary

Overall, we were very impressed with Stripe's webhook docs and think they're a great example to follow for others looking to make their webhook documentation amazing.

They had two of the more advanced features that we rarely see in the CLI for local testing and official libraries for signature verification.

Our only recommendations would be to make the event schemas a bit easier to find for webhook users, provide some options like Svix Play for users to get instant access to an endpoint URL for testing, and to include the full retry schedule in the documentation.

---

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.