Webhook security checklist: How to build secure webhooks

Why are you here?

Let’s not waste time. You’re here because you’re building a webhook feature in your app. Unfortunately, there are quite a few things that can go wrong from a security perspective. This article aims to ensure that you’re not making any well-known mistakes while building webhooks.

How do webhooks work?

As a quick recap, webhooks are HTTP(S) requests to third parties to inform them about something that happened in your app. For example, if you offer an application that generates invoices, you might offer your customers the opportunity to set up webhook functionality that is triggered when a new invoice is created. This means that when the invoice is created, your application will send a HTTP(S) request to a location that is determined by the user. The user can use this to set up their own custom workflows that are triggered by the webhook, such as scheduling reminder emails, or sending the customer a message on Slack.

Checklist: securing webhook implementations

1. Defeating SSRF-type attacks

In this type of attack, the attacker tries to get information (e.g. instance metadata in a cloud) by exploiting the webhook feature. To counter it, you should take the following measures.

✅ Validate user input

• Basic: Perform simple URL validation.
• Better: Ensure URL starts with "https://", disallow "file://" and other non-HTTPS schemes.

✅ Restrict Local Addresses

• Block typical local IPs: 127.0.x, 192.168.x, 172.x.
• Prohibit "localhost" and "http://"

✅ Limit Log Exposure

• Show only HTTP status codes in user-facing logs.
• Avoid displaying headers or body content.

✅ Advanced: Enhanced URL Validation

• Require a specific response header for POST requests, unique to the customer.
• Maintain this verification continuously, even after initial setup, to counter DNS changes..

2. Allow your users to verify data authenticity

Your webhook consumer must have a way to know the data really comes from your app. You can use any of the following methods.

✅ Test Message Verification

First, enable users to trigger a test message to test security mechanisms.

✅ HMAC Verification Hash

One of the most effective security mechanisms for webhooks functionalities is implementing HMAC for data integrity and authenticity.

The basic process can be summarized as follows:

• Generate a hash of the payload using SHA-256 and a secret key.
• Send the HMAC with the payload.
• Recipients recreate the hash to verify payload authenticity and integrity.

✅ Timestamp Inclusion

This is more of an advanced security mitigation. Add a timestamp to the payload to prevent replay attacks. Ensures messages are not reused or altered.

✅ Client-Side TLS Certificates

Authenticate HTTP calls with client-side TLS certificates. This is particularly appealing for enterprise-level consumers.

3. Rate limit and avoid data overexposure

For webhook security, sending too little data is more secure than attaching too much. Although webhook callbacks should be encrypted using HTTPS, you can never know who might be in control of a domain name after a few years.

✅ Minimize Data Exposure

• Avoid sending Personally Identifiable Information (PII) or sensitive data.
• Instead of sending multiple data points (like contact_id, email, name), just send the contact_id. Let users fetch additional data through your public API if needed.

✅ Retry Policy Communication

• Clearly communicate the retry policy and rate limits to users.
• Inform them that due to retries, messages may arrive out of order.
• Define that any 2xx response is a success; other responses should trigger a retry.

✅ Use a Queue System for Delivery

Implement a queue system to manage webhook delivery and throttle output. This approach helps prevent accidentally overwhelming your users' servers in edge cases, like a large CSV import triggering excessive webhook calls and retries.

4. Bonus: Anomaly alerting

This is more for developer convenience than security, but it's a good thing to implement nonetheless.

• Alert users when 4xx and 5xx responses are encountered
• Send notifications to inform users of any failures

This addition enhances transparency and responsiveness in your webhook system.

Conclusion

And there you have it! We've covered some steps to make your webhooks not just functional, but also secure and user-friendly. Implementing these steps will safeguard your app and also enhance the overall user experience. Happy coding! 🚀🔒👨‍💻

Aikido Security is a developer-centric software security platform. We help keep your product secure, so that you can focus on writing code. You don’t need to talk to a sales team - just connect your GitHub, GitLab, Bitbucket or Azure DevOps account to start scanning your repos for free.