# Connections

A connection lets you route events from a [Source](/docs/sources) to a [Destination](/docs/destinations). Your existing connections are viewable on the [Connections](https://dashboard.hookdeck.com/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](#create-a-connection) on a single source.

> To fan out a single source to multiple destinations, [create a new connection](#create-a-connection) using an existing source.

A connection's [rules](#connection-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](#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](#disable-a-connection).

## 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.

[Read the full Connections Guide](/docs/guides/connections-walkthrough)

## Create a connection

Creating a connection in your project allows you to route events from a single [source](/docs/sources) to one or more [destinations](/docs/destinations).

### Dashboard
1. Open the [Connections](https://dashboard.hookdeck.com/connections) page.
2. Click + Connection in the header.
3. 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.
4. Enter the Create new destination form or click the Use existing destination tab and select an existing destination.
5. Configure the appropriate Connection Rules for your new connection.
6. (Optional) Give the new connection a name.
7. Click + Create.

### CLI

```bash
# Create with inline source and destination
hookdeck connection create \
  --name "production-webhooks" \
  --source-type WEBHOOK --source-name "stripe-prod" \
  --destination-type HTTP --destination-name "my-api" \
  --destination-url https://api.example.com/webhooks

```

See the [CLI Connection Commands](/docs/cli#connection) reference for all available options.

### API
`POST /2025-07-01/connections`

**Request body example**
```json
{
  "name": "shopify-my-api",
  "source": {
    "name": "shopify"
  },
  "destination": {
    "name": "my-api",
    "config": {
      "url": "https://mock.hookdeck.com/example"
    }
  }
}
```

**Response example**
```json
{
  "id": "web_nbbweTiOtzsm",
  "team_id": "tm_lbhzBKgFOUnB",
  "updated_at": "2026-01-14T13:36:41.582Z",
  "created_at": "2026-01-14T13:36:41.595Z",
  "paused_at": null,
  "name": "shopify-my-api",
  "rules": [],
  "description": null,
  "destination": {
    "id": "des_TU9ioCk5EHUU",
    "team_id": "tm_lbhzBKgFOUnB",
    "updated_at": "2026-01-14T13:36:41.584Z",
    "created_at": "2026-01-14T13:35:55.263Z",
    "name": "my-api",
    "description": null,
    "type": "HTTP",
    "config": {
      "url": "https://mock.hookdeck.com/example",
      "rate_limit": null,
      "rate_limit_period": "second",
      "http_method": null,
      "path_forwarding_disabled": false,
      "auth": {},
      "auth_type": "HOOKDECK_SIGNATURE"
    },
    "disabled_at": null
  },
  "source": {
    "id": "src_qa5626p6y5o79b",
    "team_id": "tm_lbhzBKgFOUnB",
    "updated_at": "2026-01-14T13:36:41.583Z",
    "created_at": "2026-01-14T13:35:55.226Z",
    "name": "shopify",
    "description": null,
    "type": "WEBHOOK",
    "config": {
      "allowed_http_methods": [
        "POST",
        "PUT",
        "PATCH",
        "DELETE"
      ],
      "custom_response": null
    },
    "url": "http://localhost:8787/qa5626p6y5o79b",
    "disabled_at": null,
    "authenticated": false
  },
  "disabled_at": null,
  "full_name": "shopify -> shopify-my-api"
}
```

Your new connection is now active and accepting requests. To temporarily halt requests over this connection, [pause the connection](#pause-a-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. The execution order of transformations and filters is configurable by dragging them in the UI or ordering them in the `rules[]` array in the API.

![Rules](./images/rules-overview.png)

### Rule types

Types of rules available in Hookdeck: deduplicate, transform, filter, delay, and retry.

#### Deduplicate rule

The deduplicate rule prevents duplicate events from being processed and delivered to your destination.

For more information on how to set up deduplication, see our [deduplication documentation](/docs/deduplication).

#### 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](/docs/transformations).

#### 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](/docs/filters).

#### 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](/docs/retries#automatically-retry-events) 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](/docs/retries#manually-retry-events) after exceeding this limit.

## Configure connection rules

Configuring connection rules to control your connection routing logic.

### Dashboard
1. Open the [Connections](https://dashboard.hookdeck.com/connections) page.
2. Click the line that connects a source to a destination.
3. 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](#connection-rules).
  * To change the order of rules, drag and drop them into the desired sequence.
4. Click Save.

### CLI

```bash
# Set retry rules using the --rules flag
hookdeck connection upsert my-connection \
  --source-name my-source --source-type WEBHOOK \
  --destination-name my-destination --destination-type HTTP \
  --destination-url https://example.com/webhooks \
  --rules '[{"type": "retry", "strategy": "linear", "interval": 60000, "count": 5, "response_status_codes": ["429", "500", "502"]}]'

# Or update connection rules using a JSON file
hookdeck connection upsert my-connection \
  --rules-file connection-rules.json

```

See the [CLI Connection Commands](/docs/cli#connection) reference for all available options.

### API
`PUT /2025-07-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_FMKlTwAoGFRu",
  "team_id": "tm_lbhzBKgFOUnB",
  "updated_at": "2026-01-14T13:36:41.659Z",
  "created_at": "2026-01-14T13:36:06.347Z",
  "paused_at": null,
  "name": "shopify-orders",
  "rules": [
    {
      "type": "retry",
      "count": 5,
      "interval": 3600000,
      "strategy": "linear",
      "response_status_codes": null
    },
    {
      "body": {
        "type": "customer.subscription.updated"
      },
      "type": "filter"
    }
  ],
  "description": null,
  "destination": {
    "id": "des_TU9ioCk5EHUU",
    "team_id": "tm_lbhzBKgFOUnB",
    "updated_at": "2026-01-14T13:36:41.615Z",
    "created_at": "2026-01-14T13:35:55.263Z",
    "name": "my-api",
    "description": null,
    "type": "HTTP",
    "config": {
      "url": "https://mock.hookdeck.com/example",
      "rate_limit": null,
      "rate_limit_period": "second",
      "http_method": null,
      "path_forwarding_disabled": false,
      "auth": {},
      "auth_type": "HOOKDECK_SIGNATURE"
    },
    "disabled_at": null
  },
  "source": {
    "id": "src_qa5626p6y5o79b",
    "team_id": "tm_lbhzBKgFOUnB",
    "updated_at": "2026-01-14T13:36:41.615Z",
    "created_at": "2026-01-14T13:35:55.226Z",
    "name": "shopify",
    "description": null,
    "type": "WEBHOOK",
    "config": {
      "allowed_http_methods": [
        "POST",
        "PUT",
        "PATCH",
        "DELETE"
      ],
      "custom_response": null
    },
    "url": "http://localhost:8787/qa5626p6y5o79b",
    "disabled_at": null,
    "authenticated": false
  },
  "disabled_at": null,
  "full_name": "shopify -> shopify-orders"
}
```

[How to Order Transformations & Filters](/docs/guides/how-to-order-transformations-and-filters "Learn how to control the order of transformations and filters in your connections.")

### 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](#connection-rules).

### Dashboard
1. Open the [Connections](https://dashboard.hookdeck.com/connections) page.
2. Click the line that connects a source to a destination.
3. The connection popup should open with a connection form.
4. 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](#connection-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.
5. Click Save.

### CLI

```bash
# Update connection name and rules
hookdeck connection upsert my-connection \
  --rules-file updated-rules.json

```

See the [CLI Connection Commands](/docs/cli#connection) reference for all available options.

### API
`PUT /2025-07-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_FMKlTwAoGFRu",
  "team_id": "tm_lbhzBKgFOUnB",
  "updated_at": "2026-01-14T13:36:41.659Z",
  "created_at": "2026-01-14T13:36:06.347Z",
  "paused_at": null,
  "name": "shopify-orders",
  "rules": [
    {
      "type": "retry",
      "count": 5,
      "interval": 3600000,
      "strategy": "linear",
      "response_status_codes": null
    },
    {
      "body": {
        "type": "customer.subscription.updated"
      },
      "type": "filter"
    }
  ],
  "description": null,
  "destination": {
    "id": "des_TU9ioCk5EHUU",
    "team_id": "tm_lbhzBKgFOUnB",
    "updated_at": "2026-01-14T13:36:41.615Z",
    "created_at": "2026-01-14T13:35:55.263Z",
    "name": "my-api",
    "description": null,
    "type": "HTTP",
    "config": {
      "url": "https://mock.hookdeck.com/example",
      "rate_limit": null,
      "rate_limit_period": "second",
      "http_method": null,
      "path_forwarding_disabled": false,
      "auth": {},
      "auth_type": "HOOKDECK_SIGNATURE"
    },
    "disabled_at": null
  },
  "source": {
    "id": "src_qa5626p6y5o79b",
    "team_id": "tm_lbhzBKgFOUnB",
    "updated_at": "2026-01-14T13:36:41.615Z",
    "created_at": "2026-01-14T13:35:55.226Z",
    "name": "shopify",
    "description": null,
    "type": "WEBHOOK",
    "config": {
      "allowed_http_methods": [
        "POST",
        "PUT",
        "PATCH",
        "DELETE"
      ],
      "custom_response": null
    },
    "url": "http://localhost:8787/qa5626p6y5o79b",
    "disabled_at": null,
    "authenticated": false
  },
  "disabled_at": null,
  "full_name": "shopify -> shopify-orders"
}
```

## Pause a connection

Pausing a connection temporarily halts the routing of events from a [source](/docs/sources) to a [destination](/docs/destinations). A paused connection appears as a disconnected yellow line in the Connections page.

### Dashboard
1. Open the [Connections](https://dashboard.hookdeck.com/connections) page.
2. Click the line that connects a source to a destination.
3. Click Pause.> To resume a paused connection, follow the instructions above and click Unpause.

### CLI

```bash
# Pause a connection
hookdeck connection pause my-connection

# Unpause a connection
hookdeck connection unpause my-connection

```

See the [CLI Connection Commands](/docs/cli#connection) reference for all available options.

### API
`PUT /2025-07-01/connections/:id/pause`

**Response example**
```json
{
  "id": "web_FMKlTwAoGFRu",
  "team_id": "tm_lbhzBKgFOUnB",
  "updated_at": "2026-01-14T13:36:41.715Z",
  "created_at": "2026-01-14T13:36:06.347Z",
  "paused_at": "2026-01-14T13:36:41.715Z",
  "name": "shopify-orders",
  "rules": [
    {
      "type": "retry",
      "count": 5,
      "interval": 3600000,
      "strategy": "linear",
      "response_status_codes": null
    },
    {
      "body": {
        "type": "customer.subscription.updated"
      },
      "type": "filter"
    }
  ],
  "description": null,
  "destination": {
    "id": "des_TU9ioCk5EHUU",
    "team_id": "tm_lbhzBKgFOUnB",
    "updated_at": "2026-01-14T13:36:41.615Z",
    "created_at": "2026-01-14T13:35:55.263Z",
    "name": "my-api",
    "description": null,
    "type": "HTTP",
    "config": {
      "url": "https://mock.hookdeck.com/example",
      "rate_limit": null,
      "rate_limit_period": "second",
      "http_method": null,
      "path_forwarding_disabled": false,
      "auth": {},
      "auth_type": "HOOKDECK_SIGNATURE"
    },
    "disabled_at": null
  },
  "source": {
    "id": "src_qa5626p6y5o79b",
    "team_id": "tm_lbhzBKgFOUnB",
    "updated_at": "2026-01-14T13:36:41.615Z",
    "created_at": "2026-01-14T13:35:55.226Z",
    "name": "shopify",
    "description": null,
    "type": "WEBHOOK",
    "config": {
      "allowed_http_methods": [
        "POST",
        "PUT",
        "PATCH",
        "DELETE"
      ],
      "custom_response": null
    },
    "url": "http://localhost:8787/qa5626p6y5o79b",
    "disabled_at": null,
    "authenticated": false
  },
  "disabled_at": null,
  "full_name": "shopify -> shopify-orders"
}
```

## 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](/docs/requests#ignored-events)

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

### Dashboard
1. Open the [Connections](https://dashboard.hookdeck.com/connections) page.
2. Click the line that connects a source to a destination.
3. Click ••• button in the bottom right corner of the popup.
4. Click Disable Connection.

### CLI

```bash
# Disable a connection
hookdeck connection disable my-connection

```

See the [CLI Connection Commands](/docs/cli#connection) reference for all available options.

### API
`PUT /2025-07-01/connections/:id/disable`

**Response example**
```json
{
  "id": "web_FMKlTwAoGFRu",
  "team_id": "tm_lbhzBKgFOUnB",
  "updated_at": "2026-01-14T13:36:41.672Z",
  "created_at": "2026-01-14T13:36:06.347Z",
  "paused_at": null,
  "name": "shopify-orders",
  "rules": [
    {
      "type": "retry",
      "count": 5,
      "interval": 3600000,
      "strategy": "linear",
      "response_status_codes": null
    },
    {
      "body": {
        "type": "customer.subscription.updated"
      },
      "type": "filter"
    }
  ],
  "description": null,
  "destination": {
    "id": "des_TU9ioCk5EHUU",
    "team_id": "tm_lbhzBKgFOUnB",
    "updated_at": "2026-01-14T13:36:41.615Z",
    "created_at": "2026-01-14T13:35:55.263Z",
    "name": "my-api",
    "description": null,
    "type": "HTTP",
    "config": {
      "url": "https://mock.hookdeck.com/example",
      "rate_limit": null,
      "rate_limit_period": "second",
      "http_method": null,
      "path_forwarding_disabled": false,
      "auth": {},
      "auth_type": "HOOKDECK_SIGNATURE"
    },
    "disabled_at": null
  },
  "source": {
    "id": "src_qa5626p6y5o79b",
    "team_id": "tm_lbhzBKgFOUnB",
    "updated_at": "2026-01-14T13:36:41.615Z",
    "created_at": "2026-01-14T13:35:55.226Z",
    "name": "shopify",
    "description": null,
    "type": "WEBHOOK",
    "config": {
      "allowed_http_methods": [
        "POST",
        "PUT",
        "PATCH",
        "DELETE"
      ],
      "custom_response": null
    },
    "url": "http://localhost:8787/qa5626p6y5o79b",
    "disabled_at": null,
    "authenticated": false
  },
  "disabled_at": "2026-01-14T13:36:41.672Z",
  "full_name": "shopify -> shopify-orders"
}
```

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.

### Dashboard
1. Open the [Connections](https://dashboard.hookdeck.com/connections) page.
2. Click the disabled line that connects a source to a destination.
3. Click ••• button in the bottom right corner of the popup.
4. Click Enable Connection.

### CLI

```bash
# Enable a connection
hookdeck connection enable my-connection

```

See the [CLI Connection Commands](/docs/cli#connection) reference for all available options.

### API
`PUT /2025-07-01/connections/:id/enable`

**Response example**
```json
{
  "id": "web_FMKlTwAoGFRu",
  "team_id": "tm_lbhzBKgFOUnB",
  "updated_at": "2026-01-14T13:36:41.702Z",
  "created_at": "2026-01-14T13:36:06.347Z",
  "paused_at": null,
  "name": "shopify-orders",
  "rules": [
    {
      "type": "retry",
      "count": 5,
      "interval": 3600000,
      "strategy": "linear",
      "response_status_codes": null
    },
    {
      "body": {
        "type": "customer.subscription.updated"
      },
      "type": "filter"
    }
  ],
  "description": null,
  "destination": {
    "id": "des_TU9ioCk5EHUU",
    "team_id": "tm_lbhzBKgFOUnB",
    "updated_at": "2026-01-14T13:36:41.615Z",
    "created_at": "2026-01-14T13:35:55.263Z",
    "name": "my-api",
    "description": null,
    "type": "HTTP",
    "config": {
      "url": "https://mock.hookdeck.com/example",
      "rate_limit": null,
      "rate_limit_period": "second",
      "http_method": null,
      "path_forwarding_disabled": false,
      "auth": {},
      "auth_type": "HOOKDECK_SIGNATURE"
    },
    "disabled_at": null
  },
  "source": {
    "id": "src_qa5626p6y5o79b",
    "team_id": "tm_lbhzBKgFOUnB",
    "updated_at": "2026-01-14T13:36:41.615Z",
    "created_at": "2026-01-14T13:35:55.226Z",
    "name": "shopify",
    "description": null,
    "type": "WEBHOOK",
    "config": {
      "allowed_http_methods": [
        "POST",
        "PUT",
        "PATCH",
        "DELETE"
      ],
      "custom_response": null
    },
    "url": "http://localhost:8787/qa5626p6y5o79b",
    "disabled_at": null,
    "authenticated": false
  },
  "disabled_at": null,
  "full_name": "shopify -> shopify-orders"
}
```

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

### Dashboard
1. Open the [Connections](https://dashboard.hookdeck.com/connections) page.
2. Click the line that connects a source to a destination.
3. Click ••• button in the bottom right corner of the popup.
4. Click Delete Connection.
5. Click Delete Connection to confirm.

### CLI

```bash
# Delete a connection
hookdeck connection delete my-connection

```

See the [CLI Connection Commands](/docs/cli#connection) reference for all available options.

### API
`DELETE /2025-07-01/connections/:id`

**Response example**
```json
{
  "id": "web_FMKlTwAoGFRu"
}
```

Your deleted connection will no longer ingest or route events.