Shopify Webhooks Review
Shopify is an amazing product that lets entrepreneurs set up an online store. They have a very well documented API with a webhook feature so we took a look to see how they’ve designed their webhook offering and how they’ve documented it.
When we look at webhook solutions, we’re generally looking for 7 things: signature verification, retries, manual retries, exponential backoff, visibility/logs, event types, and multiple endpoint support.
TL;DR:
✅ Signature Verification
✅ Retries
✅ Exponential Backoff
⬜ Manual Retries
✅ Visibility into Logs
✅ Event Types
✅ Multiple Endpoints Support
To start, their documentation looks great! Kudos to the designer.
They’ve also separated the API endpoint reference from their webhook overview/configuration information which is very common. They’ve also done a good job linking between them to make sure people can find the information they’re looking for.
We also liked that they listed the limitations of their webhook offerings up front:
One thing we found a bit harsh was their webhook timeout (the default time window after which they consider your webhook to have failed) is only 5 seconds. We've seen most timeouts be ~10 seconds but have seen some up to 30 seconds. Longer is not necessarily better but 5s is probably too short.
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.
Shopifiy’s webhook implementation allows users to specify 3 request headers including a SHA256 hash that lets their users verify that the webhook was sent from Shopify.
Retries ✅
Webhook messages fail all the time for various reasons. Without retries, your users are going to be missing a lot of notifications which is a terrible user experience.
Shopify retries failed webhooks 19 times over a span of 48 hours before they disable the endpoint.
Exponential Backoff ✅
Exponential backoff is an algorithm that increases the delay between retries exponentially. This ensures that your system won’t get bottleneck from having to re-queue failed webhooks while also giving users time to fix broken endpoints before they burn through all their retry attempts.
It’s not explicitly stated that their retry schedule follows an exponential backoff algorithm. There is an explanation in the troubleshooting section that says they do increase the time between retries so it seems like they’ve implemented it but it was pretty hard to find. We would recommend stating this explicitly in the description of retries.
Manual Retries
In the event that a user’s endpoint is failing, its nice to give the developer tasked with debugging the endpoint, the option to initiate a retry manually instead of having to wait for the next scheduled retry (this could be several hours of waiting if they’re close to the end of the retry schedule).
We could not find any mention of triggering retries manually.
Visibility into Logs ✅
Giving users visibility into the delivery logs is critical for troubleshooting/debugging. Shopify’s docs are very detailed in explaining various troubleshooting strategies and they do an amazing job of making it easy for developers to find problem endpoints with both their webhook metrics and log/delivery details.
Event Types ✅
Event types are identifiers denoting the type of message being sent and are the primary way for webhook consumers to configure what events they are interested in receiving.
Shopify’s various event types are listed in their Webhhook API reference.
Multiple Endpoint Support ✅
Many webhook solutions only allow one endpoint URL to be specified where all messages will be received. By enabling your users to create multiple endpoints, they’ll be able to choose which endpoints receive which messages. Multiple endpoint support and event types go hand in hand.
Shopify’s “Create a New Webhook” endpoint allows users to create new endpoints by specifying an address and a topic.
Summary
Overall, Shopify’s webhook docs are very thorough and they offer a lot of the features that contribute to an excellent developer experience. Our only improvements to suggest would be to add manual retries, be more specific about the retry schedule and whether it follows an exponential backoff schedule, and expand the timeout window to 10 seconds.
If you’re looking to implement webhooks at Shopify’s level, consider trying Svix, our webhooks as a service product that makes it super easy to build a secure, reliable, and scalable webhook solution through an API.