Fanning out webhooks by using Hookdeck

In this guide, we will look at how Hookdeck's webhook delivery behavior acts as a data transfer engine when considering fan-out ingress. We will go through a simple step-by-step example that illustrates how to set up fan-out on Hookdeck using the UI, as well as how to to use the event filtering feature to customize our fan-out.

How Hookdeck delivers data

After ingesting webhooks sent to a Source (a Hookdeck unique URL), Hookdeck copies each event and delivers it to all the associated destinations (connections).

We recommend using a Source per webhook publisher. This implies you will be subscribing to multiple topics using the same URL, thus receiving different type events.

There are two main benefits to this behavior:

1. The obvious benefit is it allows Hookdeck to act as a data transfer engine for fanning out webhooks.
2. Hookdeck allows developers to benefit from a single persistent URL per Source, reducing the overhead when managing webhook endpoints.

A drawback to this behavior is that we are fanning EVERY received event to all its destinations, which might not be the desired outcome (see more in the example). To solve this issue, we are going to leverage the event filtering feature. We can write a json that will act as an event filter that allows Hookdeck to know what event is expected per destination. This customizes the fan-out behavior, as well as allows you to be extremely specific regarding which event you want to be delivered to your Services.

Example

Let's jump into an example to see how this translates into a real scenario. Let's say you have 3 services that listen to Shopify "order create" and "order update" topics. Read how set up Shopify webhooks.

Your services are:

1. Notification: a service to notify you for every order.
2. WMS: a service that triggers action in your Warehouse Management Solution based on the webhook.
3. Gift Card: a service that only triggers an action when there's a gift card in the order.

What does this look like in Hookdeck?

Here we have Shopify as a Source and 3 connections without any filter set up. Learn how to create a connection

With this current setup, every time Hookdeck receives a webhook from an "order create" and an "order update," it will be copied and delivered to all 3 services. However, our Gift Card service only wants to listen to orders with gift cards in the request. This means that for every order without a gift card, we want the event to be delivered to the Notification and WMS services, but when there's a gift card in the request, we want the event to be fanned out to all three Services.

Setting up the event filter

Let's set up the event filter for the Gift Card connection on Hookdeck to implement the scenario discussed above.

1. Click the event filter icon in the gift-card connection
2. Insert the JSON for the filter (see below)
3. Click Save

{
"line_items":[
  {
    "gift_card":true
  }]
}

Great! Now Hookdeck will only deliver webhooks with a "giftcard": true to our Gift Card Service.

Conclusion

In this guide, we learned about Hoodkeck's webhook delivery behavior and how it allows you to fan out your webhooks to multiple destinations, as well as how to customize this behavior by leveraging the event filtering feature.