Connections

Link sources to destinations with optional filters and transforms.

Connections link a source to a destination. When an event arrives at a source, hookstream evaluates all connections for that source. If the event passes the connection's filters, it is optionally transformed via a JSONata expression and then delivered to the destination.

Filters & transforms

Content-based filters use 9 operators: eq, neq, contains, gt, gte, lt, lte, exists, in. Filters reference event fields using dot-notation paths (e.g., payload.data.status, headers.x-event-type, method). All filters must match for the event to be routed (AND logic).

JSONata transforms are expressions applied to the event payload before delivery. Use transforms to reshape data, extract fields, add computed values, or convert formats. The transform receives the full event body and must return a valid JSON object.

List Connections

GET /v1/connections

List all connections for the authenticated organization.

Authentication: API key or session cookie.

Query Parameters

source_id string

Filter connections by source.

destination_id string

Filter connections by destination.

cursor string

Cursor for pagination.

limit number default: 20

Number of results to return (max 100).

bash
curl https://hookstream.io/v1/connections \
  -H "X-API-Key: $HOOKSTREAM_API_KEY"

json
{
  "connections": [
    {
      "id": "conn_c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8",
      "source_id": "src_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
      "destination_id": "dst_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
      "filter_rules": [
        { "field": "payload.type", "op": "eq", "value": "order.created" }
      ],
      "transform_expression": null,
      "source_name": "Stripe Webhooks",
      "destination_name": "Backend API",
      "created_at": "2026-02-28T12:00:00Z"
    }
  ],
  "cursor": null,
  "has_more": false
}

Create Connection

POST /v1/connections

Create a connection between a source and a destination.

Authentication: API key or session cookie.

Body Parameters

source_id string required

The source to receive events from.

destination_id string required

The destination to deliver events to.

filter_rules array

Array of filter rule objects: { field, op, value }. Operators: eq, neq, contains, gt, gte, lt, lte, exists, in.

transform_expression string

JSONata expression to transform the event payload before delivery.

transform_enabled boolean default: false

Whether to apply the transform expression.

bash
curl -X POST https://hookstream.io/v1/connections \
  -H "X-API-Key: $HOOKSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "src_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "destination_id": "dst_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
    "name": "Stripe to Backend",
    "filter_rules": [
      { "field": "payload.type", "op": "eq", "value": "order.created" }
    ],
    "transform_enabled": true,
    "transform_expression": "{ \"orderId\": data.id, \"total\": data.amount / 100 }"
  }'

json
{
  "id": "conn_c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8",
  "source_id": "src_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "destination_id": "dst_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
  "name": "Stripe to Backend",
  "filter_rules": [
    { "field": "payload.type", "op": "eq", "value": "order.created" }
  ],
  "transform_enabled": true,
  "transform_expression": "{ \"orderId\": data.id, \"total\": data.amount / 100 }",
  "created_at": "2026-03-01T12:00:00Z"
}

Retrieve Connection

GET /v1/connections/:id

Get a single connection by ID.

Authentication: API key or session cookie.

json
{
  "id": "conn_c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8",
  "source_id": "src_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "destination_id": "dst_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
  "name": "Stripe to Backend",
  "filter_rules": [
    { "field": "payload.type", "op": "eq", "value": "order.created" }
  ],
  "transform_enabled": true,
  "transform_expression": "{ \"orderId\": data.id, \"total\": data.amount / 100 }",
  "source_name": "Stripe Webhooks",
  "destination_name": "Backend API",
  "created_at": "2026-02-28T12:00:00Z",
  "updated_at": "2026-03-01T08:00:00Z"
}

Update Connection

PATCH /v1/connections/:id

Update a connection's filters or transform.

Authentication: API key or session cookie.

bash
curl -X PATCH https://hookstream.io/v1/connections/conn_c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8 \
  -H "X-API-Key: $HOOKSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter_rules": [
      { "field": "payload.type", "op": "eq", "value": "order.created" },
      { "field": "payload.data.amount", "op": "gt", "value": 1000 }
    ]
  }'

json
{
  "id": "conn_c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8",
  "filter_rules": [
    { "field": "payload.type", "op": "eq", "value": "order.created" },
    { "field": "payload.data.amount", "op": "gt", "value": 1000 }
  ],
  "updated_at": "2026-03-01T15:00:00Z"
}

Delete Connection

DELETE /v1/connections/:id

Delete a connection. Events already in the pipeline are still delivered.

Authentication: API key or session cookie.

json
{ "success": true }

Was this page helpful?

Previous Destinations

Next Events