Github Webhooks Review
GitHub is a platform for hosting and managing software projects. It is a web-based platform that uses the Git version control system to allow developers to collaborate on code and build software together.
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
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.
Github supports signing webhooks with a user defined secret token. This is unusual as most services simply provide a secure secret token instead of having the user generate one themselves to ensure the secret is secure. They also use SHA-256 with HMAC to generate the signature hash. They also warn their users against using variable time comparison algorithms to avoid timing based oracle attacks like the Jenkins webhook plugin vulnerability we discussed in this blog article.
Retries
Webhook messages often fail. Without retries, users may miss many notifications which results in a bad user experience.
Github does not offer automatic retries of failed webhook messages.
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.
There is no exponential backoff because Github does not offer automatic 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).
Github has an excellent user interface for examining the last 30 days of webhook messages which includes a button for re-sending specific messages.
Visibility into Logs ✅
Giving users visibility into the delivery logs is critical for troubleshooting/debugging.
Github has an excellent user interface for examining your webhook requests:
They show you the event that triggered the webhook, a timestamp, its status, and a link to view more details including the full response.
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.
There is an extensive list of available event types with code samples here: Github Event Payloads.
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.
Github allows you to create up to 20 endpoints per event for each installation target (organization or repository).
Summary
We liked the user interface of the recent delieveries log and the callout to their users to beware they're using constant time comparison algorithms for verifying signatures. However, we think the lack of automatic retries could contribute to a poor developer experience.
If you’re looking to implement world class webhooks, consider trying Svix, the enterprise ready webhooks service. Svix makes it super easy to build a secure, reliable, and scalable webhook solution through an API.