Securing your webhook API – the 13 requirements you need to know

Webhook APIs are gaining popularity within enterprises as a cost-effective, efficient integration mechanism for application to application (A2A) and business to business (B2B) integrations. However, if you are implementing webhooks for enterprise then security becomes a primary consideration. In this blog post, I’ll take you through the 13 requirements you need to know for securing your webhook API solution.

What is a webhook API?

First to make sure we are all on the same page here is a quick recap of what a webhook API is:

REST API vs webhook API

As the diagram above highlights, a webhook API is an API where the API provider publishes data to the consumer when an event occurs. In comparison, a REST API is an API where the API consumer posts to (or requests data from) the provider. These two APIs work together. You can think that for every REST API call an event is triggered (an order is created, a like event, etc), in addition, events can also be schedule-driven.

3 Pillars of Security

When addressing security using the CIA triad – Confidentiality, Integrity and, Availability – provides a good structure. Here is a quick recap of the CIA triad:

Confidentiality – that information is not made available or disclosed to unauthorized individuals, entities, or processes.

Integrity – that data cannot be modified in an unauthorized or undetected manner.

Availability – the information must be available when it is needed

So let’s get into it.

Confidentiality

Confidentiality has the largest number of security concerns that need to be addressed. These include:

  • Ensuring only authorized API consumers can discover and subscribe to your webhooks.
  • API providers being able to verify the API consumers server.
  • API consumers being able to verify the API providers server.
  • Encrypting the connection and data at rest.

Ensuring only authorized API consumers can discover and subscribe

The first step is making sure that only authorized developers can discover and subscribe to your webhook APIs.

If we don’t do this then we are opening our webhook APIs to any user. This would be called a public webhook and most enterprises don’t want this.

To satisfy this requirement it is best practice to integrate with a trusted identity and authorization service that can handle the authentication requirements within the enterprise (e.g. 2FA, SSO).

It is also important to make sure your solutions support authorization based on groups so that it’s not required to set up discovery authorization for each and every single developer. Rather developers can be placed in groups in your identity platform and your webhook API solution should understand these groups and be able to connect them with individual APIs.

Requirement 1 – Ensure your webhook API solution is integrated with a trusted identity and authorization service.

Requirement 2 – Make sure your webhook API solution supports authorized consumer grouping to easily manage discoverability

API providers being able to verify the API consumers server

The next concern is ensuring that when transmitting data to an API consumer you are able to verify it’s being sent to the correct server.

If we don’t ensure the correct server is the recipient then our webhook API solution becomes vulnerable to man-in-the-middle attacks. This is where a hacker intercepts messages and re-transmits them to the intended receiver undetected.

To ensure that we are connecting to the right server we can use TLS to verify the server’s certificate. The API provider (which is the TLS client in the client-server interaction) can ensure that the server’s certificate is not expired and that the domain name or IP address on the certificate matches the server’s information.

Using the latest version of TLS is important to ensure that any known vulnerabilities of older versions are not an attack vector.

Requirement 3 – Make sure you are using the latest version of TLS to verify the server of the API consumer.

API consumers being able to verify the API providers server

The API consumers endpoint, that is receiving the data from the server, is going to be often open to the internet. It is imperative then that the API consumer can verify that data being sent to it is coming from authorized API providers.

There are a number of techniques that can be used to verify the provider’s server and depending on the desired security levels it may be appropriate to apply a few. The techniques include mutual TLS, using a token or shared secret, and adding the IP addresses to an allow list.

Mutual TLS is viewed as the best practice for securing server-to-server communication. With mutual TLS both the certificate of the server is validated as well as the client’s certificate is validated. If either of the certificates is not valid then the connection is not set up.

A token such as a bearer token (from an OAuth server) or a shared secret (e.g Basic Authentication, HMAC signature, API key) is another layer that can be applied. While not as secure as Mutual TLS (as secrets and tokens are easier for a hacker to acquire than a private certificate and associated password, as they are transmitted or sometimes cached) it can provide another layer of security to your webhook API solution.

Lastly, the most brute force technique is adding the API provider’s servers’ IP addresses to an allow list. This technique is effective but can reduce the robustness of the connection as IP addresses can change (due to migrations or by adding proxy servers). This technique doesn’t add any requirement to your webhook API solution as it is implemented outside of it.

Requirement 4 – Make sure to support mutual TLS with your webhook API solution with the latest version of TLS.

Requirement 5 – Make sure your webhook API solution supports at least one of the techniques of shared secrets or tokens e.g. Basic Authentication, HMAC signatures, API key, OAuth 2.0.

Encrypting the connection and data at rest

Next is to make sure that data being transferred can not be snooped and that data stored at rest can not be easily read by an unauthorized user.

The first part of this requirement is already solved with the use of TLS so the focus here will be on ensuring your data is encrypted at rest.

Encrypting your data at rest means that if any unauthorized user gets hold of the disk, your data is stored on, that they can’t easily extract the data from it.

Why would your webhook API solution store data you might ask? Well in order to ensure the availability of data, which we will get to soon, your webhook API solution needs to ensure guaranteed delivery to the API consumers and in order for the solution to be trusted your webhook API solution is going to need to provide the capability for your consumers to inspect the traffic sent to it. For both these requirements, data will be stored (at least for a short period of time) in your webhook API solution.

So if data is stored we need to ensure that the data is encrypted at rest. This can be achieved by ensuring either your file system and/or database supports this requirement.

Requirement 6 – Make sure your file system and/or database support encryption at rest and make sure it’s turned on.

Integrity

Verifying the message integrity is another concern of the API consumers. If there has been a man-in-the-middle attack, either because mutual TLS is not used or because a hacker has found a previously unknown vulnerability, then they can modify the message and send it on to the consumer unbeknownst to them.

To mitigate this a digital signature can be applied to the message by the provider that can be verified by the consumer. One of the techniques widely used with webhooks for digital signatures is the HMAC signature which encrypts a hash of the message using a shared secret. The API consumer upon receiving the message can decrypt the signature using the shared secret, generate a hash of the message and compare it with the one hash sent in the signature. If they match they know that message has not been tampered with.

Requirement 7 – Make sure your webhook API solution supports digital signatures i.e. the HMAC technique

Availability

Last but not least with the CIA triad is availability and it is perhaps the most important (it’s ok to make data secure but if it’s not available to authorized users when they need it then it’s not much point).

There are a few security concerns when it comes to webhook solutions related to availability and these include:

  • Performant and Scalable – webhook APIs are event-driven, this means your API consumers want the data when the event happens, not seconds or minutes later.
  • Robust – API consumers servers can be down for maintenance or because of an outage. This does not mean that they do not want the events when they come back online. Therefore having a retry strategy is critical and if required enabling your API consumer to resend an event.
  • API Consumers availability – any endpoint that is exposed to the internet can be attacked either on purpose by a hacker or even by accident (endless loop posting data) – i.e. DDoS or replay attacks -therefore you need a strategy for your API consumers to mitigate these attack vectors.

Performant and scalable

When building or implementing your webhook API solution you need to ensure that it is both performant and scalable. Events and their subscribers quickly multiple when you adopt the event-driven architecture approach so making sure your architecture scales is important.

Make sure the solution that you are implementing scales natively horizontally both at the service and data layer. At the same time, you need to ensure that throughput time is minimal and doesn’t grow when you add subscribers or load.

Requirement 8 – Ensure your webhook API architecture scales horizontally to support future loads both at the service layer and at the data layer.

Robust

Your webhook API solution will need to be fault-tolerant both to failures in its own architecture as well as to failures in your API consumers architecture. This means that your webhook API solution needs to be of high quality with how it handles exceptions and it also means that when exceptions occur on your API consumers side that you can handle them in the correct way.

For instance, if you get a server error from your API consumer you need to be able to retry the message so that when their server comes back online it gets the message. Alternatively, if you get an error indicating that the data could not be processed because the data was incorrect you need to put that message to one side so that it can be inspected later (retrying that message won’t help).

You will also need to give your API consumers the ability to resend a message either because they have recently resolved an issue that caused a message failure or because they had a long downtime and the retries had expired.

Lastly, when discussing availability and robustness there is no bigger test than recovering from a disaster (DR). DR is a large topic and would need its own blog but suffice to say that you will need to ensure your webhook API solution has a DR plan that fits into your enterprise’s wider business continuity plan.

Requirement 9 – Ensure you are working with or developing a high-quality, highly available, and fault-tolerant webhook API solution – a quick and dirty solution won’t cut it.

Requirement 10 – Make sure your webhook API solution correctly handles API consumer exceptions.

Requirement 11 – Make sure your API consumers can inspect the traffic and have the ability to resend a message if required.

API Consumers availability

As mentioned previously your API consumers have an endpoint exposed to the internet and that means it can come under attack either intentionally or even in some cases unintentionally. Here we are referring to primarily DDoS attacks and replay attacks. Therefore there is a need to put some strategies in place to help out your API consumers.

The first strategy is a simple one, make sure you include the timestamp of the transaction in the headers and in the signature of each of the messages. That way the API consumer can detect replay attacks and offload those requests on the edge of their architecture.

A further capability that can be added to your webhook API solution is the ability to throttle transactions to your API consumers to minimize the risk of unintentional DDoS attacks.

Finally, the responsibility to prevent these attacks lies with the architecture of your API consumer. They need to ensure that they can detect DDoS attacks and have the ability to offload the request traffic at the edge of their architecture.

Requirement 12 – Make sure your webhook API solution includes the timestamp of the event in the message headers and in the signature so that replay attacks can be detected.

Requirement 13 – Make sure your API solution supports transaction throttling to your API consumer’s endpoint.

Conclusion

A webhook API solution is a modern and agile approach to event-driven data integration that is gaining popularity in enterprise integration. As with any enterprise solution, security is a key concern. When choosing whether to build or buy your next webhook API solution make sure it will meet the security requirements that your enterprise will need.

If you are looking for a webhook solution that will scale with you, check out webhookie. With a community edition that is open source and free to use you can get started fast.

Leave a comment

Your email address will not be published.