A developer's guide to webhook security

Webhooks keep applications informed of changes in other systems. They enable developers to react to these changes, such as a successful payment or a newly opened pull request. 

Webhook notifications are extremely handy for staying up to date with ever-changing information, but are they secure? As webhook consumers, how do we know the webhook is being sent from the desired source? And, can we be certain the message we receive hasn’t been tampered with? 

As developers who consume webhooks, it is on us to make sure webhook providers prioritize security and offer answers to these questions. It’s also our responsibility to utilize the security measures that webhook providers offer.

Here are some considerations webhook consumers should take into account to ensure that their webhooks are secure. You can find more details about these methods and others at webhooks.fyi.

Use HTTPS

For starters, like all of your other web traffic, you want to make sure you’re operating over HTTPS. 

The most foundational aspect of webhook security is confirming the sender and the payload of each message. While most webhooks don’t encrypt the payload, using HTTPS can mitigate both eavesdropping and man-in-the-middle (MITM) attacks, where an attacker can intercept and modify the payload before forwarding it to the receiver. 

Leverage webhook providers’ security features

While most webhook providers do not provide security measures, many do. In webhook communications, authentication, message integrity validation, replay prevention validation, and enforcement all happen on the webhook listener. Security controls from the webhook provider help the receiver validate the messages' authenticity and prevent tampering. However, most providers don’t require consumers to use the security they provide. 

It’s up to the consumers to read the webhook documentation of the provider to know what options are available, understand them, and then implement them. 

Restrict who can send a webhook request

An added measure of ensuring webhooks are being sent from the desired source is to restrict which IPs those messages are being sent from. 

Some providers, like GitHub or Zoom, provide a public list of IPs used in their service to send webhook notifications. Developers can use this list to implement network restrictions and ensure that only the webhook service sends notifications. This isn’t feasible if the webhook service doesn’t list its origin IPs, but it should be implemented whenever possible.

Store secrets securely

Several of the methods for securing webhooks involve credentials and shared secrets. These tokens must be treated as confidential information and handled carefully by both the webhook provider and consumer. They should be stored in a safe place that’s encrypted like a secrets vault. 

It’s also a good idea to change or rotate secrets on a regular basis or after important events — such as when an employee leaves the organization — to mitigate risk if the secret is compromised. Just like changing passwords periodically, rotating secrets reduces the risk of unauthorized access. It's an extra precaution to ensure that the webhook system stays locked down and protected.

Call back the service

Another way to validate a webhook is to make a separate call back to the provider to verify the change in data. Once a webhook request is made you can use an alternate channel, like the service's REST API, to confirm the contents of the webhook. For example, a transaction transferring a large sum of money or deleting critical data should be checked before marking an order as paid or cleaning up records. This additional step helps confirm the event's legitimacy and ensures that developers are dealing with accurate information.

Secure with ngrok

Consumers of webhooks don’t have to implement all of these security methods on their own. ngrok provides built-in webhook verification with over 50 of the industry's leading providers. The Webhook Verification module authenticates that webhook requests are being sent by the expected webhook provider and the messages are not tampered with. The module also prevents replay attacks when providers like Calendly and Slack support it. Sign up for an ngrok account and give it a try!

Learn more about webhook security best practices

These are only a few of the best practices recommended at webhooks.fyi, a resource we’ve shared with the development community to define standards for using and developing webhooks. 

When it comes to security, it’s a developer’s responsibility to ensure that the webhooks they are consuming are valid and secure. They should use HTTPS and leverage webhook providers' security features. These best practices ensure the privacy, authenticity, and integrity of webhook messages. Following them builds a solid foundation for webhooks to work their magic and facilitate seamless integration between otherwise disconnected systems.

Interested in learning more about testing, ngrok, or how to get started with ingress to your production apps? Check out these resources from the ngrok blog:

• Webhook verification with ngrok edges 
• Kubernetes ingress with HashiCorp Consul and ngrok
• How ngrok actively prevents phishing attacks

Questions or comments? Hit us up on X (aka Twitter) @ngrokhq or LinkedIn, or join our community on Slack.

‍