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 .

connections-list

You can individually edit each connection with the options menu.

Create a connection

Connections can be created with the Create button at the top of the page or by clicking the ➕ connections below an existing Source.

connection-create

The fields for creating a new webhook connection are:

FieldDescriptionRequired
SourceYou can select an already existing source or create a new onetrue
DestinationYou can select an already existing destination or create a new onetrue
RulesetIf left empty it will default to Default Rulesetfalse
NameA human friendly unique ID to make API calls idempotenttrue

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.

Every connection with the same Source uses the same URL to receive events. This means you can have a single URL to send events to multiple destinations.

Update a connection

You can update a connection by clicking the connection itself. You can also edit any property related to a webhook connection.

connection-update

Changing your connection Source will also change the connection name.

Pause a connection

Connections can be temporarely paused in the UI or the API.

When a connection is paused, webhooks events will be placed ON HOLD by Hookdeck. Once the connection is unpaused, Hookdeck will deliver events that was placed ON HOLD and continue delivering events normally.

Make sure to set a rate limit for your destinations before unpausing a connection to protect your servers from receiving webhook events faster than it can process!

Archive a connection

Connections can be temporarily or permanently disabled by archiving them using the UI or the API. Archived connections will no longer deliver your webhooks to your destination, and the webhooks won't be saved. However, your Webhook URL will still return an HTTP 200 to your source. If you do not intend to unarchive the connection, we recommend removing the Webhook URL in your webhook provider.

archive-connection

When unarchiving, the connection will restart receiving and sending your webhooks; however, the webhooks received while archived will not be available or replayed.

Delete a connection

To preserve the webhooks history, connections cannot be deleted. If you wish to disable a connection to stop receiving events, see "Archiving".

If you absolutely need a connection removed, please contact us and we will take care of it.

Using rules

Connections inherit it's Ruleset rules but can also defined Custom Rules to have apply specific rules to that connection.

Learn more about Rules & Ruleset

Add a Custom Rule

Click on the connection you want to add a custom rule. Then select Edit.

Edit a connection

Select the rules you want to add. In this image we decided to add a Custom Rule for the Retry and Alert, thus overriding the existing logic from the Ruleset.

Create a custom rule

Remove a Custom Rule

To remove a Custom Rule, click the Delete icon and then Save.

Delete a custom rule

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"
  }
}

When in doubt, we recommend taking this approach.

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.