Webhook Delivery

Learn how Hookdeck uses Connections as the basis to manage your webhook delivery. Find out what's the perfect setup for your use case.

Default Behavior

Hookdeck's delivery is a one-to-many relationship.

When Hookdeck receives a webhook to a Source URL, the webhook is copied and delivered to EVERY connection related to the Source.

default behavior

In this situation, Hookdeck delivers webhook from stripe to stripe-service and github to git-service.

Fan out

Since Hookdeck's delivery is a one-to-many relation, if you want your webhooks delivered to multiple Destinations (endpoints), you simply need to add a new connection to an existing Source.

So by default, your connections will have a fan-out behavior.

fan out

In this situation, Hookdeck delivers EVERY webhooks from shopify to notifcation, wms, and gift-card.

Routing

When it comes to routing webhooks, you have two options based on how you want to manage your connections.

  1. Create a new Source per each topic (1 Source URL per subscription)
  2. Create one Source for all your topics per API provider. (1 Source URL: per API provider)

Choosing option 2 is our preferred solution because it allows you to take full advantage of Hookdeck. However, Option 1 is also extremely viable for many use cases.

Let's take a closer look at #2

Pros of Option 2

  • 1 URL per API provider
  • Manage all of your webhook routing within Hookdeck

Hookdeck's fan out behavior is the basis of routing. Since a webhook is copied and delivered to EVERY connection related to the Source, all you can add filter by connection to specify what webhooks you want to receive.

Filters

Filters are criteria you define by connection to tell Hookdeck which webhooks you want.

Learn everything about Filters here

Apply Connection Filters on a webhook's:

  • Body
  • Header
  • Query
  • Path

The filters are additive. A connection can have a filter on the all or a combination of Body, Header, Query,and Path.

routing

In this situation,

  • notification will only receive webhooks that includes the Query
{
  "storeid": "001"
}
  • wms will only receive webhook that has a Path of /wms AND Headers of
{
  "x-shopify-topic": "orders/create"
}
  • gift-card will only receive webhooks that has gift-card is true in the Body of the request
{
  "line_items": [
    {
      "gift_card": true
    }
  ]
}

Body, Header, and Query filters use a JSON syntax. Get familiar with it here

Routing Tutorial