GitLab Webhooks Review
GitLab is a DevOps platform for shipping and deploying software to the cloud. They offer source code management, continuous integration and deployment, and infrastructure automation.
One thing to note about GitLab's webhooks is that they have a default rate limit enforced based on your plan tier:
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.
GitLab supports sending a secret token in the X-Gitlab-Token HTTP header of the webhook request. It's not clear what type of encryption is used on the token and there is no code sample of how to validate the token that would be useful for their users.
Retries ✅
Webhook messages often fail. Without retries, users may miss many notifications which results in a bad user experience.
GitLab supports automatic retries when webhooks return a response code of 5xx. Retries are attempted for 24 hours. It is noted in the docs that this is not yet ready for production use for self-managed GitLab implementations.
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 stated that the backoff is exponential but they do increase the interval between retries which is the import thing to do. With their automatic retries for 24 hours with exponential backoff, GitLab is following best practices to give their users time to debug failing webhook endpoints before they're disabled.
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).
GitLab has a manual retry feature under their Webhook settings. They have several options to test each endpoint.
Visibility into Logs ✅
Giving users visibility into the delivery logs is critical for troubleshooting/debugging.
GitLab has a "Recent Events" view that shows you the status of webhook requests over the last 2 days to help with troubleshooting.
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: Webhook events.
There is also a filtering mechanism to specify which branches you want to trigger events.
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.
You can create multiple endpoints in the webhook settings section of you GitLab account by specifying a URL, secret token, and an event to trigger the webhook.
Summary
GitLab's webhook system checked all our boxes. They did a great job explaining and showing examples of how to set up a webhook receiver as well as how to troubleshoot common issues.
If you’re looking to implement world class webhooks like GitLab, 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.