Connections

A connection lets you route events from a source to a destination. Your existing connections are viewable on the Connections dashboard page, grouped by source.

How connections work

When Hookdeck receives a request from a source, a copy of the request is routed over every connection attached to that source. For one-to-many delivery, create multiple connections on a single source.

To fan out a single source to multiple destinations, create a new connection using an existing source.

A connection's rules - including automatic retries, filters, and transformations - dictate how each event is routed along that connection, and what happens when a delivery attempt fails.

Pause a connection to temporarily halt its routing of events. Pausing a connection is particularly useful when troubleshooting a destination server, or during outages. When a connection is permanently retired, it can be disabled.

Best practices for connections

There's no right or wrong way to structure your connections. We've listed two popular approaches below - usually we recommend the first, but the second has its own unique advantages.

Connection per event type

In this approach, each connection routes to a single, event type-specific endpoint on your destination.

For example, a Shopify Order → Create Gift Card connection might allow a new Shopify order to execute a createGiftCard method on your destination service.

This approach provides the clearest architectural context to your team working in Hookdeck. Visibility and troubleshooting from within Hookdeck are improved, since each connection maps to a specific user story.

Connection per service

In this alternative approach, each connection routes an entire service to your destination.

For example, you might enable a Shopify → My API connection to pass all Shopify events to your service. In this case, you would handle the routing of different types of data to various methods within your API based on the contents of the event.

This approach allows you to have fewer connections overall. The downside is that you lose a level of granularity within Hookdeck.

Create a connection

Creating a connection in your project allows you to route events from a single source to one or more destinations.

Open the Connections page.
Click Connection in the header.
Enter the Create new source form or click the Use existing source tab and select an existing source.
To route events from an already-existing source to an additional destination, select the relevant source in the list.
Enter the Create new destination form or click the Use existing destination tab and select an existing destination.
Configure the appropriate Connection Rules for your new connection.
(Optional) Give the new connection a name.
Click Create.

POST

/2024-09-01/connections

Request body example JSON

{
  "name": "shopify-my-api",
  "source": {
    "name": "shopify"
  },
  "destination": {
    "name": "my-api",
    "url": "https://example.com/webhook"
  }
}

Response example JSON

{
  "id": "web_3tVBgTFuuzmEnsWa9eBywz6j",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "disabled_at": null,
  "updated_at": "2021-08-02T14:12:56.575Z",
  "created_at": "2021-08-02T14:12:56.611Z",
  "paused_at": null,
  "name": "shopify-my-api",
  "destination": {
    "id": "des_Nm49lhZV6wVrN1XFFPfkv7Zk",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "url": "https://example.com/webhook",
    "disabled_at": null,
    "updated_at": "2021-08-02T14:12:56.591Z",
    "created_at": "2021-08-02T14:12:56.589Z",
    "rate_limit": null,
    "rate_limit_period": "second",
    "cli_path": null,
    "path_forwarding_disabled": false,
    "name": "my-api",
    "http_method": "POST",
    "auth_method": {
      "type": "HOOKDECK_SIGNATURE",
      "config": {}
    }
  },
  "source": {
    "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "disabled_at": null,
    "updated_at": "2021-08-02T14:12:56.586Z",
    "created_at": "2021-08-01T21:29:41.788Z",
    "name": "shopify",
    "url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW",
    "allowed_http_methods": [
      "PUT",
      "PATCH",
      "DELETE",
      "POST"
    ],
    "custom_response": null,
    "verification": null
  },
  "rules": []
}

Your new connection is now active and accepting requests. To temporarily halt requests over this connection, pause the connection.

To enable one-to-many delivery, repeat this process and select an already-existing source in the Source dropdown.

Connection rules

A rule is a piece of instructional logic that dictates the behavior of events routed through a connection.

Rules

Rule types

Four types of rules are available in Hookdeck: transform, filter, delay, and retry.

Transform rule

The transform rule allows you to modify the payload of a event before it gets delivered to a destination.

For more information on how to set up transformations, see our transformation documentation.

Filter rule

The filter rule allows you to route events differently based on the contents of their Headers, Body, Query, and/or Path.

For more information on how to set up filters, see our filter documentation.

Delay rule

The delay rule allows you to introduce a delay between the moment Hookdeck receives an event, and when it's forwarded to your destination.

Retry rule

The retry rule determines the rate and limit of automatic retries on failed events.

Configuration	Explanation
Strategy	A linear strategy means retries will occur at regular intervals; an exponential strategy means each retry will be delayed twice as long as the previous (1 hour, 2 hours, 4 hours...)
Interval	The delay between each automatic retry
Count	The number of automatic retries Hookdeck will attempt after an event fails
HTTP status codes	The HTTP status codes that should be retried.

Automatic retries max out after one week, or 50 attempts - whichever comes first. Events can be manually retried after exceeding this limit.

Configure connection rules

Configuring connection rules to control your connection routing logic.

Open the Connections page.
Click the line that connects a source to a destination.
Make the desired edits in the Connection Rules section.
- To remove a rule, click the trash icon next to the rule.
- To add a rule, click the rule button at the bottom. For information on each available rule type, see the rules overview.
Click Save.

PUT

/2024-09-01/connections/:id

Request body example JSON

{
  "rules": [
    {
      "type": "retry",
      "count": 5,
      "interval": 3600000,
      "strategy": "linear"
    },
    {
      "body": {
        "type": "customer.subscription.updated"
      },
      "type": "filter"
    }
  ]
}

Response example JSON

{
  "id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "disabled_at": null,
  "updated_at": "2021-08-02T14:12:56.748Z",
  "created_at": "2021-08-01T21:29:41.818Z",
  "paused_at": null,
  "name": "mock-api",
  "rules": [],
  "destination": {
    "id": "des_fYYCay655IHwbOMhIaUXtNq2",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "url": "https://mock.hookdeck.com",
    "disabled_at": null,
    "updated_at": "2021-08-02T14:07:54.608Z",
    "created_at": "2021-08-01T21:29:41.785Z",
    "rate_limit": null,
    "rate_limit_period": "second",
    "cli_path": "/",
    "path_forwarding_disabled": false,
    "name": "mock-api",
    "http_method": "POST",
    "auth_method": {
      "type": "HOOKDECK_SIGNATURE",
      "config": {}
    }
  },
  "source": {
    "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "disabled_at": null,
    "updated_at": "2021-08-02T14:12:56.674Z",
    "created_at": "2021-08-01T21:29:41.788Z",
    "name": "shopify",
    "url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW",
    "allowed_http_methods": [
      "PUT",
      "PATCH",
      "DELETE",
      "POST"
    ],
    "custom_response": null,
    "verification": null
  }
}

How rules affect previous events

Changes to rules apply differently to previously-received events, depending on the rule changed.

Rule changed	Retroactive behavior for events
Transform	Does not impact previously-received events; only applies to events received after the rule is changed
Filter	Does not impact previously-received events; only applies to events received after the rule is changed
Delay	Does not impact previously-received events; only applies to events received after the rule is changed
Retry	Impacts previously-received, failing events after their next scheduled attempt occurs

Edit a connection

Editing a connection allows you to change its name, and rules.

Open the Connections page.
Click the line that connects a source to a destination.
The connection popup should open with a connection form.
Make the desired edits to the connection.
- To edit the connection's name, change the text in the Connection Name section.
- To edit the connection's rules, set the desired options in the Connection Rules section.
- You can also click Open Connection to open the Connection details page for further updates.
Click Save.

PUT

/2024-09-01/connections/:id

Request body example JSON

{
  "rules": [
    {
      "type": "retry",
      "count": 5,
      "interval": 3600000,
      "strategy": "linear"
    },
    {
      "body": {
        "type": "customer.subscription.updated"
      },
      "type": "filter"
    }
  ]
}

Response example JSON

{
  "id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "disabled_at": null,
  "updated_at": "2021-08-02T14:12:56.748Z",
  "created_at": "2021-08-01T21:29:41.818Z",
  "paused_at": null,
  "name": "mock-api",
  "rules": [],
  "destination": {
    "id": "des_fYYCay655IHwbOMhIaUXtNq2",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "url": "https://mock.hookdeck.com",
    "disabled_at": null,
    "updated_at": "2021-08-02T14:07:54.608Z",
    "created_at": "2021-08-01T21:29:41.785Z",
    "rate_limit": null,
    "rate_limit_period": "second",
    "cli_path": "/",
    "path_forwarding_disabled": false,
    "name": "mock-api",
    "http_method": "POST",
    "auth_method": {
      "type": "HOOKDECK_SIGNATURE",
      "config": {}
    }
  },
  "source": {
    "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "disabled_at": null,
    "updated_at": "2021-08-02T14:12:56.674Z",
    "created_at": "2021-08-01T21:29:41.788Z",
    "name": "shopify",
    "url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW",
    "allowed_http_methods": [
      "PUT",
      "PATCH",
      "DELETE",
      "POST"
    ],
    "custom_response": null,
    "verification": null
  }
}

Pause a connection

Pausing a connection temporarily halts the routing of events from a source to a destination. A paused connection appears as a disconnected yellow line in the Connections page.

Open the Connections page.
Click the line that connects a source to a destination.
Click Pause.

To resume a paused connection, follow the instructions above and click Unpause.

PUT

/2024-09-01/connections/:id/pause

Response example JSON

{
  "id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "disabled_at": null,
  "updated_at": "2021-08-02T14:12:56.779Z",
  "created_at": "2021-08-01T21:29:41.818Z",
  "paused_at": "2021-08-02T14:12:56.779Z",
  "name": "mock-api",
  "rules": [],
  "destination": {
    "id": "des_fYYCay655IHwbOMhIaUXtNq2",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "url": "https://mock.hookdeck.com",
    "disabled_at": null,
    "updated_at": "2021-08-02T14:07:54.608Z",
    "created_at": "2021-08-01T21:29:41.785Z",
    "rate_limit": null,
    "rate_limit_period": "second",
    "cli_path": "/",
    "path_forwarding_disabled": false,
    "name": "mock-api",
    "http_method": "POST",
    "auth_method": {
      "type": "HOOKDECK_SIGNATURE",
      "config": {}
    }
  },
  "source": {
    "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "disabled_at": null,
    "updated_at": "2021-08-02T14:12:56.674Z",
    "created_at": "2021-08-01T21:29:41.788Z",
    "name": "shopify",
    "url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW",
    "allowed_http_methods": [
      "PUT",
      "PATCH",
      "DELETE",
      "POST"
    ],
    "custom_response": null,
    "verification": null
  }
}

Disable a connection

Disabling a connection temporarily stops all events going to that connection and removes it from your Connections page. When a connection is disabled it will no longer generate Events and will result in a Ignored Event

If there are pending Events associated with the the connection, they will be updated with the error code "CANCELLED" and marked as "FAILED".

Open the Connections page.
Click the line that connects a source to a destination.
Click ••• button in the bottom right corner of the popup.
Click Disable Connection.

PUT

/2024-09-01/connections/:id/disable

Response example JSON

{
  "id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "disabled_at": "2021-08-02T14:12:56.779Z",
  "updated_at": "2021-08-02T14:12:56.779Z",
  "created_at": "2021-08-01T21:29:41.818Z",
  "paused_at": null,
  "name": "mock-api",
  "rules": [],
  "destination": {
    "id": "des_fYYCay655IHwbOMhIaUXtNq2",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "url": "https://mock.hookdeck.com",
    "disabled_at": null,
    "updated_at": "2021-08-02T14:07:54.608Z",
    "created_at": "2021-08-01T21:29:41.785Z",
    "rate_limit": null,
    "rate_limit_period": "second",
    "cli_path": "/",
    "path_forwarding_disabled": false,
    "name": "mock-api",
    "http_method": "POST",
    "auth_method": {
      "type": "HOOKDECK_SIGNATURE",
      "config": {}
    }
  },
  "source": {
    "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "disabled_at": null,
    "updated_at": "2021-08-02T14:12:56.674Z",
    "created_at": "2021-08-01T21:29:41.788Z",
    "name": "shopify",
    "url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW",
    "allowed_http_methods": [
      "PUT",
      "PATCH",
      "DELETE",
      "POST"
    ],
    "custom_response": null,
    "verification": null
  }
}

Your disabled connection will no longer ingest or route events, although your source provider will still receive an HTTP 200 response when making requests.

Enable a connection

Enabling a connection returns that connection to its previously active state. Notice that connections are created enabled by default.

Open the Connections page.
Click the disabled line that connects a source to a destination.
Click ••• button in the bottom right corner of the popup.
Click Enable Connection.

PUT

/2024-09-01/connections/:id/enable

Response example JSON

{
  "id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "disabled_at": null,
  "updated_at": "2021-08-02T14:12:56.813Z",
  "created_at": "2021-08-01T21:29:41.818Z",
  "paused_at": null,
  "name": "mock-api",
  "rules": [],
  "destination": {
    "id": "des_fYYCay655IHwbOMhIaUXtNq2",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "url": "https://mock.hookdeck.com",
    "disabled_at": null,
    "updated_at": "2021-08-02T14:07:54.608Z",
    "created_at": "2021-08-01T21:29:41.785Z",
    "rate_limit": null,
    "rate_limit_period": "second",
    "cli_path": "/",
    "path_forwarding_disabled": false,
    "name": "mock-api",
    "http_method": "POST",
    "auth_method": {
      "type": "HOOKDECK_SIGNATURE",
      "config": {}
    }
  },
  "source": {
    "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "disabled_at": null,
    "updated_at": "2021-08-02T14:12:56.674Z",
    "created_at": "2021-08-01T21:29:41.788Z",
    "name": "shopify",
    "url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW",
    "allowed_http_methods": [
      "PUT",
      "PATCH",
      "DELETE",
      "POST"
    ],
    "custom_response": null,
    "verification": null
  }
}

The connection will now resume routing events, but the events received while it was disabled will not be available for replaying.

Delete a connection

Deleting a connection permanently disables that connection and removes it from your Connections page. Associated event data is retained for the remainer of your retention window and will be displayed with a Connection Deleted label.

If there are pending Events associated with the the connection, they will be updated with the error code "CANCELLED" and marked as "FAILED".

Open the Connections page.
Click the line that connects a source to a destination.
Click ••• button in the bottom right corner of the popup.
Click Delete Connection.
Click Delete Connection to confirm.

DELETE

/2024-09-01/connections/:id

Response example JSON

{
  "id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp"
}

Your deleted connection will no longer ingest or route events.

<- Previous Authentication Next -> Sources