Fan-Out Routing

Fan-out routing lets you send a single event and have Nahook automatically deliver it to every endpoint subscribed to that event type.

How It Works

Your Server                    Nahook
    │                            │
    │  POST /ingest/event/       │
    │  order.created             │
    │ ─────────────────────────> │
    │                            │── Delivery → Endpoint A (subscribed)
    │    202 Accepted            │── Delivery → Endpoint B (subscribed)
    │ <───────────────────────── │── Skip Endpoint C (not subscribed)
    │                            │

Instead of calling the ingestion API once per endpoint, you call it once with the event type. Nahook handles the fan-out.

Sending Fan-Out Events

Use the event type ingestion endpoint:

curl -X POST https://api.nahook.com/api/ingest/event/order.created \
  -H "Authorization: Bearer nhk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "orderId": "ord_123",
      "amount": 99.99,
      "currency": "USD",
      "customer": {
        "id": "cust_456",
        "email": "[email protected]"
      }
    }
  }'

const response = await fetch(
  "https://api.nahook.com/api/ingest/event/order.created",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer nhk_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      payload: {
        orderId: "ord_123",
        amount: 99.99,
        currency: "USD",
        customer: {
          id: "cust_456",
          email: "[email protected]",
        },
      },
    }),
  },
);

const result = await response.json();
console.log(result);
// {
//   eventTypeId: "evt_abc123",
//   deliveryIds: ["del_xxx", "del_yyy"],
//   status: "accepted"
// }

The response includes a deliveryIds array — one delivery per subscribed endpoint.

Adding Metadata

You can attach metadata to fan-out events for filtering and organization:

curl -X POST https://api.nahook.com/api/ingest/event/order.created \
  -H "Authorization: Bearer nhk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": { "orderId": "ord_123" },
    "metadata": {
      "region": "us-east-1",
      "priority": "high"
    }
  }'

Metadata values must be strings, with a maximum of 10 key-value pairs.

Environment Scoping

Fan-out delivery respects environment boundaries:

1. The API key determines the environment
2. Only endpoints in the same environment are eligible
3. The event type must be published in that environment

This means a staging API key will never accidentally deliver to production endpoints, even if they're subscribed to the same event type.

Fan-Out vs Direct Delivery

Use direct delivery when you know the exact endpoint. Use fan-out when your system publishes events and consumers (endpoints) subscribe to what they need.