Managing Connections

Webhook connections are used to connect a Source and a Destination. By creating a connection you tell Hookdeck who will be sending the webhook events and where you wish them to be sent.

Browsing your connections

Connections are listed under the Connections page of your dashboard.

Connections are grouped by Source and listed below each of your sources.

connections-list

Each connection can be individually edited, with the options menu.

Create a connection

Connections can be created with the Create button at the top of the page or by adding a connection to a Source via the Add button bellow a Source.

connection-create

The fields for creating a new webhook connection are:

Field	Description	Required
`Source`	You can select an already existing source or create a new one	true
`Destination`	You can select an already existing destination or create a new one	true
`Ruleset`	If left empty it will default to `Default Ruleset`	false
Label	If left empty it will default to `Source Label -> Destination Label`	false
Alias	A human friendly unique ID to make API calls idempotent	false

If your connection uses a new Source, you will be provided with a unique URL to copy and paste in your Source. Otherwise, your Source has been set up, webhook events will now be sent to your configured Destination.

Update a connection

A connection can be updated via the options menu. Every property of a webhook connection can be updated.

connection-update

Delete a connection

Currently, for technical reasons, connections cannot be deleted. We generally recommend reusing a connection that's no longer useful. The options to archive / delete webhooks will be added in a future release.

Best Practices

A question that often comes up is "how to structure your connection?". There is no 'incorrect' approach. Here are two patterns that could best fit your use case.

Connection per use case

You can structure your connections to map to a specific use case. For example, a webhook labeled Shopify Order → Create Gift Card would be used to describe a webhook for the Shopify webhook topic order/created and an endpoint on your service that executes the createGiftCard method (ie: https://my-api.com/webhooks/createGiftCard)

Since Hookdeck provides a single URL for each Source, you can create as many destinations for that source without adding the overhead of managing multiple webhook URL.

This approach is very convenient to help you troubleshoot issues and monitor events since it gives Hookdeck more information about the context of those webhook events.

Additionally, if you are worried about getting irrelevant events to your endpoint, you can also apply a filter to the connection. For example, we could set a filter to only receive orders that contain a Gift Card.

{
  "items": {
    "type": "Gift"
  }
}

Connection per service

The alternative approach is to create a connection per service. You could set a connection labeled Shopify → My API with a Destination URL of https://my-api.com/webhooks/shopify. In this case, you would handle the routing to different methods within your API based on the content of the webhook.

The benefit of this approach is that you tend to have fewer connections but the tradeoff is losing a level of granularity within Hookdeck.