Managing

The simplicity of webhooks makes the burden of management hard to see in the beginning. But as you keep using webhooks and adding more providers and consumers, the management required for this communication link starts to grow.

In this article, we will go through the most common management problems faced when working with webhooks and how to solve them with Hookdeck. Each problem tackled will also include a small discussion section to expand on the problem.

The burden of webhook management

Setup inconsistency

The process of setting up webhooks on each provider’s platform is almost as diverse as the number of available providers. This makes it difficult to transfer the knowledge of setting up webhooks from one provider to another. Also, providers often change the setup flow from time to time.

Payload formats

The message format is also different from provider to provider. Message structure, headers, and data formats (XML or JSON) are all different. These varying differences require that each provider’s payload is handled differently.

Security

There is also the issue of security, and each webhook provider handles security differently. Though security strategies are standard and limited (basic authentication, API tokens, and signature verification, to name a few), providers support a varying number of them.

You can learn more about webhook security in our Complete Guide to Webhook Security.

Multiple providers and consumers

Chances are that you won’t be processing webhooks from just one provider. For example, you might have an e-commerce site set up using Shopify while processing payments with Stripe, so you have to work with both Shopify and Stripe webhooks. Because of the differences in how both providers handle webhooks, you will need to make provisions for their differences and in the same vein ensure they all work well together within your application.

Also, what if you need to work with multiple consumers and route certain messages to one or a specific set of consumers?

How do you “properly” manage webhook events?

What your current stack (probably) looks like

A standard and recommended way of handling webhooks is to process them asynchronously. The most common type of asynchronous processing setup uses the _web-queue-worker_ architecture. This helps to decouple the webhook producer and consumer by buffering messages in a queue that sits between the producer and consumer.

The queue helps solve timeout issues that arise when the consumer is busy but still receiving webhooks, and ensures that messages are persistent and can be retried after errors occur.

Limitations of your current setup

While the setup described above helps in handling webhooks in a more reliable manner, it doesn’t really tackle any of the management burdens listed above out of the box (except the case with multiple consumers).

Queues don’t have message transformation features that you can configure to parse webhook messages into a format that aligns with your application or harmonize different webhook payloads. You might need to add an API gateway to achieve this, though it’s important to note that adding an API gateway is an added complexity to the overall system.

You also still need to take care of varying authentication formats and understand the queueing component well enough to route messages to the appropriate consumers.

Common webhook management problems and Hookdeck’s solutions

You need a specific payload format

Problem

You need to receive the webhook payload in a different format.

Solution

Hookdeck Transformation allows you to execute javascript on the request to update the payload.

Input

{
  "headers": {
    "content-type": "application/json"
  },
  "body": {
    "hello": "world"
  },
  "query": "?",
  "parsed_query": {}
}

Transformation

addHandler("transform", (request, context) => {
  // assign the value to the new field
  request.body.new_hello = request.body.hello;

  // delete the previous field
  delete request.body.hello;

  // return the modified request
  return request;
});

Output

{
  "headers": {
    "content-type": "application/json",
    "content-length": "21"
  },
  "body": {
    "new_hello": "world"
  },
  "query": "?",
  "parsed_query": {}
}

Discussion

Webhook producers control the format in which the webhook payload is sent. If the consumer needs the information in a different format, a transformation process needs to occur before the consumer receives the webhook.

One way to achieve this is to put a proxy server in between the webhook provider and the consumer. The proxy does the job of converting the webhook’s payload sent from the provider into a format that the consumer can work with. Another strategy is to use middleware functions to transform data received on the consumer’s endpoint.

You forgot each provider's specific policy

Problem

You need to centralize policies.

Solution

Hookdeck uses Rulesets to define a standard behavior for all webhook providers sending webhooks to your destination API. Every connection on Hookdeck uses a default ruleset that can be tweaked by defining rules on webhook retries, rate limits, and alerting.

Discussion

Each webhook provider has a different set of rules defined for handling webhooks. Differences in things like webhook timeout duration, retries, rate limiting, and alerting logic lead to a non-consistent workflow pattern when handling webhooks from multiple providers.

To mitigate this issue, you need to use a proxy server (like an API gateway) to harmonize the operations of multiple webhook providers by aligning them to a uniform set of rules defined on the proxy. These rules will control how the webhooks interact with your destination server.

You don’t know how the previous integrations were set up

Problem

You need to understand configuration at a glance.

Solution

The Connections page allows you to see the behaviors of each webhook.

Discussion

Setting up webhooks varies from provider to provider, and these providers often change the process through which their webhooks are set up. This makes the knowledge base on webhooks fragile and sometimes non-transferrable.

The recommended way to ensure easy onboarding and knowledge transferability is to adequately document the setup process for each webhook provider.

You receive multiple webhooks for the same event

Problem

You need to make your webhook endpoints idempotent.

Discussion

When providers send the same webhook request more than once, the webhook’s effect will be duplicated multiple times within the application. This puts the application in an inconsistent state and diminishes the overall integrity.

The solution is to ensure that all endpoints that will receive webhooks are idempotent. This can be achieved by checking unique webhook IDs to see if a webhook has been processed before, or by writing the webhook processing logic to be idempotent. You can learn more about it here.

You implement a different security for each provider

Problem

You need a centralized interface for authenticating webhooks.

Solution

With Hookdeck Integrations, you only need a single verification workflow for all your webhooks. You can create an integration for any webhook provider that supports Basic Auth, API keys, or HMAC, and Hookdeck Integrations will automatically merge all your authentication methods from each provider into a single authentication workflow. You can also use any of the available authentication templates for popular providers like Shopify or GitHub.

Discussion

Webhook providers offer different types of authentication methods. When working with multiple webhooks providers, you need to implement and keep track of each authentication strategy. This is not ideal as it will not scale with time and a growing number of providers.

Solving this problem requires using a web proxy like an API Gateway to abstract the authentication methods of each webhook provider into a single authentication workflow for the destination server.

The webhook provider only accepts one webhook URL

Problem

You need to fan out a single webhook to multiple locations.

Solution

Hookdeck Connections give you the ability to take a single webhook and fan out the request to multiple destinations. This removes the limitation placed on the number of destinations by the webhook provider.

Add a filter to specify the criteria on the body, header, query, or path of events that will be delivered by the connection.

Discussion

When one or more consumers depend on a webhook, you need to communicate the webhook request to multiple destinations. If your webhook provider only allows a single destination, a provision has to be made to distribute the webhook to multiple destinations.

Messaging systems are employed to solve this type of problem. A queue or pub/sub system is placed between the provider and consumer to decouple the two entities. This way, multiple consumers can subscribe to the messaging system and each gets a copy of the webhook sent by the provider.

Your server response time is causing webhooks to timeout

Problem

You need to respond to webhooks below the timeout limit.

Solution

When you set up Hookdeck connections between your providers and consumer servers, Hookdeck automatically acts as a queue between them**.** Hookdeck provisions high availability infrastructure to respond to providers under 200ms across the globe. This helps you start processing your webhooks without having to manage or deal with event-driven architecture.

Discussion

When a server exceeds its throughput, subsequent webhook requests will have to wait for the active ones to finish processing before they can be processed. If this waiting period exceeds the response time limit set by the webhook provider, the pending webhooks will be dropped.

The recommended solution is to process the webhooks asynchronously. This can be achieved by placing a queueing component between the webhook provider and your server to decouple the two entities. This way, all webhook requests will receive a response almost immediately and be queued for the server to pick up at a rate that does not exceed the server’s throughput.

Conclusion

As a platform built solely for the management of webhooks, Hookdeck comes with features that make it really easy to manage your webhooks. As more providers and consumers are added, your webhook load increases, and varying authentication schemes or custom payload transformations are required, Hookdeck ensures that you have full control over everything your application needs to manage all your webhooks.