A route connects a source to a destination, with an optional event type filter. The delivery worker uses routes to determine where to forward each inbound event.

How routing works

When an event is ingested:

1. The worker queries all routes for the account.
2. Routes are matched against the event's source_id and event_type.
3. A route matches if:
   • Its source_id matches the event's source (or is null — catch-all for all sources).
   • Its event_type_pattern matches the event's X-Event-Type header (or is null — catch-all for all event types).
4. The event is delivered to every matching destination.

Route matching examples

Route source_id	Route event_type_pattern	Matches
null	null	All events from all sources
src_abc	null	All events from source src_abc
null	payment.succeeded	payment.succeeded events from any source
src_abc	payment.*	payment.* events from source src_abc

Pattern matching

event_type_pattern supports * as a wildcard suffix. For example, payment.* matches payment.succeeded, payment.failed, etc.

Create route

POST /v1/routes

Authentication: Bearer

Request body

Field	Type	Required	Description
destination_id	UUID	Yes	Target destination
source_id	UUID	No	Restrict to events from this source. Omit for catch-all.
event_type_pattern	string	No	Filter by event type. Omit for catch-all.

Response 201 Created

{
  "data": {
    "id": "r1r2r3r4-e5f6-7890-abcd-ef1234567890",
    "account_id": "a1a2a3a4-...",
    "source_id": "s1s2s3s4-...",
    "destination_id": "d1d2d3d4-...",
    "event_type_pattern": "payment.succeeded",
    "active": true,
    "created_at": "2024-01-15T10:00:00Z"
  }
}

Errors

Status	Error	Cause
400	destination_id is required	Missing required field
400	invalid destination_id	Not a valid UUID
400	invalid source_id	Not a valid UUID
401	Unauthorized	Invalid Bearer token

curl examples

# Catch-all route: all events from all sources → destination
curl -s -X POST http://localhost:8080/v1/routes \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_id": "d1d2d3d4-..."
  }' | jq .

# Source-specific route
curl -s -X POST http://localhost:8080/v1/routes \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "s1s2s3s4-...",
    "destination_id": "d1d2d3d4-..."
  }' | jq .

# Filtered by event type
curl -s -X POST http://localhost:8080/v1/routes \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "s1s2s3s4-...",
    "destination_id": "d1d2d3d4-...",
    "event_type_pattern": "payment.succeeded"
  }' | jq .

---

List routes

GET /v1/routes

Authentication: Bearer

Response 200 OK

{
  "data": [
    {
      "id": "r1r2r3r4-...",
      "account_id": "a1a2a3a4-...",
      "source_id": "s1s2s3s4-...",
      "destination_id": "d1d2d3d4-...",
      "event_type_pattern": null,
      "active": true,
      "created_at": "2024-01-15T10:00:00Z"
    }
  ]
}

curl example

curl -s http://localhost:8080/v1/routes \
  -H "Authorization: Bearer $API_KEY" | jq .

---

Typical setup

A common configuration for receiving Stripe webhooks and routing them to two services:

# 1. Create source
SOURCE=$(curl -s -X POST http://localhost:8080/v1/sources \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Stripe"}' | jq -r '.data.id')

# 2. Create destinations
BILLING=$(curl -s -X POST http://localhost:8080/v1/destinations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Billing Service", "url": "https://billing.internal/webhooks"}' \
  | jq -r '.data.id')

ANALYTICS=$(curl -s -X POST http://localhost:8080/v1/destinations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Analytics", "url": "https://analytics.internal/webhooks"}' \
  | jq -r '.data.id')

# 3. Route all Stripe events to billing
curl -s -X POST http://localhost:8080/v1/routes \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source_id\": \"$SOURCE\", \"destination_id\": \"$BILLING\"}" | jq .

# 4. Route only payment events to analytics
curl -s -X POST http://localhost:8080/v1/routes \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source_id\": \"$SOURCE\", \"destination_id\": \"$ANALYTICS\", \"event_type_pattern\": \"payment.*\"}" | jq .

Previous pageDestinations

Next pageEvents (Inbound)