Intuit Webhooks Documentation Review

This post is a part of our "Documentation Review" series, where we collaborate with different companies to review, analyze, and share feedback on 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, so we've read a lot of webhook documentation.

Intuit is a financial technology platform that includes products like TurboTax, CreditKarma, and QuickBooks. Their webhook documentation helps app developers integrate with their QuickBooks Online product offering.

The best documentation we've seen generally includes 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: B+
Retry Policy: B+
Troubleshooting and Failure Recovery: B
Testing Tools: B+

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. The signature verification section of webhook documentation should explain the signature scheme (how the signature is created) and give instructions on how to verify the signature with code samples.

Intuit signs their webhook messages using HMAC SHA256, which is the industry standard. They also provide a sample header and a code sample in Java to help users verify the webhook. There are full example implementations in both Java and Node.js.

The only suggestion we'd have for Intuit is to include a simple webhook verification function in their SDKs to make it easier for users to verify webhook messages without needing to deal with extracting header values, dealing with the hashing algorithm, and converting values from base-64 to base-16. We've seen these as primary reasons why users struggle to verify signatures.

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 users to configure what events they are interested in receiving. The best event catalogs list every available event type with sample payload schemas and descriptions of actions that trigger each event.

Webhooks from Intuit don't have a defined event type. Instead, they specify a “name” and “operation” in the message payload, and all payloads have the same 5 fields. The fields are listed with explanations, and an example server response is provided so users know what format to expect in the response. There is also a full table of supported entities and operations so that users can know what to look for when they need to respond to different events in a specific way.

We prefer using event types since they let users filter what messages they receive at a specific endpoint instead of receiving all messages, and then filtering the responses.

Grade: B+

Retry Policy

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

The retry policy from Intuit is clearly stated in the “Use webhook best practices section” which we loved. We don't often see sections like this so kudos to Intuit for including it.

Our only critique is the timing of the retry schedule. Failed messages are retried at 20, 30, and 50 minutes. We'd suggest doing a retry very quickly to account for fluky failures (< 1 minute) then exponentially increasing the duration between retries (an example schedule could be something like 1 minute, 10 minutes, 100 minutes).

Grade: B+

Troubleshooting and Failure Recovery

Describing a few of the most common failure modes can save users time and effort when troubleshooting a failing endpoint.

We think it could also be useful to give some hints/caveats along the way for common pitfalls developers may encounter (e.g. in signature verification, a common failure is stringifying the JSON payload before creating the HMAC signature. Some stratification methods remove whitespace which will result in a different hash).

We mentioned the best practices section under retries but we wanted to mention it again here as it gives some guidance on avoiding request timeouts, preventing duplicate events, and ordering of messages using the timestamp.

We also noted that Intuit disables endpoints if they exhaust their retry schedule. It would be great if there were some instructions on how to recover messages and re-enable the endpoint once the issues are resolved.

Here is an example from our webhooks documentation:

https://docs.svix.com/receiving/using-app-portal/replaying-messages

Grade: B

Testing Tools

The main improvement we would recommend is to give users more guidance and options for testing their webhook implementations.

Intuit offers sandbox environments with sample data so that you can simulate a more normal environment while you're developing.

One feature that is very useful when setting up a webhook endpoint is the ability to send test messages. It's a much better developer experience to get a sample message sent to your new endpoint instead of needing to figure out how to trigger an actual event.

Another common tool is a test endpoint generator like Svix Play. This lets users start testing webhooks very quickly, without needing to develop their own endpoint.

Grade: B+

Summary

Webhooks documentation from Intuit has all the essentials for guiding users to a great webhook experience. Sample verification code is provided, the retry schedule is stated clearly, and there is a comprehensive list of events.

Where Intuit can improve is on “nice to have” features like testing tools and a verification function in their SDKs to offer developers an amazing webhook experience.

---

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.