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. For signature verification, our reference point is the Standard Webhooks specification, which defines the standard headers and signing scheme.
TL;DR:
✅ Signature Verification
⬜ Retries
⬜ Exponential Backoff
✅ Manual Retries
✅ Visibility into Logs
✅ Event Types
✅ Multiple Endpoints Support
What a GitHub webhook is
A GitHub webhook is an HTTP POST request that GitHub sends to a URL you register on a repository, organization, or GitHub App whenever a selected event happens, such as a push, pull request, issue, or release. Each delivery carries a JSON payload describing the event, the event name in the X-GitHub-Event header, a unique ID in X-GitHub-Delivery, and an HMAC-SHA256 signature in X-Hub-Signature-256 computed with the secret you set on the hook. Your server must answer with a 2xx status within 10 seconds or GitHub records the delivery as failed. Common uses are triggering CI builds and deploys on push, syncing issues and pull requests into trackers and chat, and auditing repository changes. Our GitHub webhook example shows the full headers and payloads of a delivery and a receiver that handles them.
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.
Looking to send webhooks at scale?
Schedule a CallRetries
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 3 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 deliveries 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.