Topics

Pub/sub topics for fan-out delivery with per-subscription filters and transforms.

Topics enable pub/sub-style fan-out delivery. Create a topic with a unique slug, subscribe destinations to it with optional per-subscription filters and transforms, then publish events to the topic. hookstream delivers the event to all matching subscribers.

Topics run alongside the connection-based pipeline, not replacing it. You can mix both patterns in the same project — use connections for direct 1-to-1 routing and topics for fan-out.

List Topics

GET /v1/topics

List all topics.

Authentication: API key or session cookie.

json
{
  "topics": [
    {
      "id": "top_d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5",
      "name": "Order Events",
      "slug": "order-events",
      "description": "All order lifecycle events",
      "subscription_count": 3,
      "created_at": "2026-02-28T10:00:00Z"
    }
  ]
}

Create Topic

POST /v1/topics

Create a new topic.

Authentication: API key or session cookie.

Body Parameters

name string required

Display name for the topic.

slug string required

URL-safe slug for the publish endpoint (e.g., "order-events").

description string

Optional description of the topic.

bash
curl -X POST https://hookstream.io/v1/topics \
  -H "X-API-Key: $HOOKSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Events",
    "slug": "order-events",
    "description": "All order lifecycle events"
  }'

json
{
  "id": "top_d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5",
  "name": "Order Events",
  "slug": "order-events",
  "description": "All order lifecycle events",
  "publish_url": "https://hookstream.io/v1/topics/order-events/publish",
  "created_at": "2026-03-01T12:00:00Z"
}

Retrieve Topic

GET /v1/topics/:id

Get a single topic by ID with its subscriptions.

Authentication: API key or session cookie.

json
{
  "topic": {
    "id": "top_d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5",
    "name": "Order Events",
    "slug": "order-events",
    "description": "All order lifecycle events",
    "publish_url": "https://hookstream.io/v1/topics/order-events/publish",
    "created_at": "2026-02-28T10:00:00Z"
  },
  "subscriptions": [
    {
      "id": "sub_e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6",
      "topic_id": "top_d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5",
      "destination_id": "dst_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
      "destination_name": "Backend API",
      "filter_rules": [],
      "transform_expression": null,
      "created_at": "2026-02-28T12:00:00Z"
    }
  ]
}

Update Topic

PATCH /v1/topics/:id

Update a topic's name or description.

Authentication: API key or session cookie.

bash
curl -X PATCH https://hookstream.io/v1/topics/top_d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5 \
  -H "X-API-Key: $HOOKSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "Order lifecycle events (created, updated, cancelled)"}'

json
{
  "id": "top_d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5",
  "name": "Order Events",
  "slug": "order-events",
  "description": "Order lifecycle events (created, updated, cancelled)",
  "updated_at": "2026-03-01T15:00:00Z"
}

Delete Topic

DELETE /v1/topics/:id

Delete a topic and all its subscriptions.

Authentication: API key or session cookie.

json
{ "success": true }

Subscribe Destination

POST /v1/topics/:id/subscriptions

Subscribe a destination to a topic.

Authentication: API key or session cookie.

Body Parameters

destination_id string required

The destination to receive events.

filter_rules array

Per-subscription content-based filter rules.

transform_expression string

Per-subscription JSONata transform expression.

bash
curl -X POST https://hookstream.io/v1/topics/top_d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5/subscriptions \
  -H "X-API-Key: $HOOKSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_id": "dst_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
    "filter_rules": [
      { "field": "payload.type", "op": "eq", "value": "order.created" }
    ]
  }'

json
{
  "subscription": {
    "id": "sub_e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6",
    "topic_id": "top_d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5",
    "destination_id": "dst_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
    "filter_rules": [
      { "field": "payload.type", "op": "eq", "value": "order.created" }
    ],
    "transform_expression": null,
    "created_at": "2026-03-01T12:00:00Z"
  }
}

Update Subscription

PATCH /v1/topics/:id/subscriptions/:sub_id

Update a subscription's filter rules or transform expression.

Authentication: API key or session cookie.

Body Parameters

filter_rules array

Updated content-based filter rules.

transform_expression string

Updated JSONata transform expression.

json
{
  "subscription": {
    "id": "sub_e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6",
    "topic_id": "top_d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5",
    "destination_id": "dst_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
    "destination_name": "Backend API",
    "filter_rules": [
      { "field": "payload.type", "op": "eq", "value": "order.updated" }
    ],
    "transform_expression": null
  }
}

Unsubscribe

DELETE /v1/topics/:id/subscriptions/:sub_id

Remove a subscription from a topic.

Authentication: API key or session cookie.

json
{ "success": true }

Publish Event

POST /v1/topics/:slug/publish

Publish an event to a topic by slug. The event is delivered to all matching subscribers.

Authentication: API key or session cookie.

bash
curl -X POST https://hookstream.io/v1/topics/order-events/publish \
  -H "X-API-Key: $HOOKSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "order.created",
    "data": { "id": "ord_789", "amount": 2500, "currency": "usd" }
  }'

json
{
  "event_id": "evt_d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9",
  "topic": "order-events",
  "received_at": "2026-03-01T14:30:00Z"
}
Previous Collections
Next Replay
Ask a question... ⌘I