Topics & Pub/Sub

Topics add a publish-subscribe messaging pattern on top of hookstream. Your application publishes events to a named topic, and every subscribed destination receives them — with optional per-subscription filters and transforms.

What are Topics?

A topic is a named channel that destinations can subscribe to. When you publish an event, hookstream fans it out to every subscribed destination, applying each subscription's filter and transform along the way.

graph LR
  P[Publisher<br/>your app] --> T[Topic<br/>order-events]
  T --> S1[Subscription A<br/>filter + transform]
  T --> S2[Subscription B<br/>filter + transform]
  T --> S3[Subscription C<br/>no filter]
  S1 --> D1[Destination 1<br/>Slack]
  S2 --> D2[Destination 2<br/>BigQuery]
  S3 --> D3[Destination 3<br/>S3 archive]

Topics run alongside the connection-based pipeline, not replacing it. Use connections for external webhook routing; use topics for application-initiated fan-out.

Creating Topics

Topics have a name and a URL-safe slug. Create one via the API:

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

The slug shows up in the publish URL: POST /v1/topics/order-events/publish.

Subscriptions

Subscribe a destination to a topic:

bash
curl -X POST https://hookstream.io/v1/topics/top_abc/subscriptions \
  -H "Authorization: Bearer $HOOKSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "destination_id": "dest_xyz" }'

Subscriptions support the same 9 filter operators as connections plus optional JSONata transforms — so different subscribers can receive different slices of the same topic, reshaped however they need. See Filters & Transforms for the operator reference.

Publishing

Publish an event to a topic and hookstream fans it out to every matching subscription:

bash
curl -X POST https://hookstream.io/v1/topics/order-events/publish \
  -H "Authorization: Bearer $HOOKSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "order.created",
    "data": { "id": "ord_123", "amount": 4999 }
  }'

Each subscription's filter runs against the published event, matching subscriptions apply their transform, and the result is handed to the destination's DeliveryScheduler DO.

Topics vs. Connections

Both move events to destinations, but they solve different problems:

• Connections are source-to-destination routes. External webhooks come in through a source and get routed out. Use them for ingesting third-party webhooks.
• Topics are a pub/sub overlay. Your application publishes directly to a topic and subscribers receive it. Use them for internal events you want to fan out to many destinations.

You can combine them: route webhooks through connections into your app, then have your app re-publish to a topic after enrichment — giving downstream systems a cleaner, normalized stream.

Next Steps