CircleCI Webhooks Review
CircleCI is a continuous integration platform that helps engineering teams automate deployments.
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.
CircleCI can append a signature to the webhook request header to allow their users to verify the origin of the webhook. They also encrypt the signature using HMAC-SHA256 with a secret key which is inline with our suggestions. They even have a code example of how users can verify the signature making this one of the best implementatinos of signature verification we've seen.
Retries
Webhook messages often fail. Without retries, users may miss many notifications which results in a bad user experience.
The CircleCI documentation does state that failed webhooks will be retried but they do not state the retry schedule. Interestingly, they acknowledge the fact that they did not document it and explain that this is because the policy is subject to change during a "preview period" that they do not specify.
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 mention of the delay between retries but again, they have acknowledged the lack of documentation on the retry policy is due to it beind subject to change.
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.
There is no mention of logs or a UI for viewing webhook statuses.
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.
CircleCI only offers two event types: workflow-comopleted and job-completed. Each webhook payload contains information about the project, organization, job, workflow, pipeline, and trigger associated with the webhook. You can find some sample webhook payloads in their documentation.
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.
CircleCI allows creating multiple endpoints through the webhooks section in the project settings as well as via their public API. However, there is a limit of 5 webhooks per project.
Summary
While we were very impressed with their treatment of signature verification, we would like to see more emphasis on helping users troubleshoot and debug failing endpoints. We'd like to see the retry policy clearly stated in their documentation. Just because its subject to change doesn't mean you can't simply update your documentation when it changes.
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 via API.