Appearance
Routes
About 554 wordsAbout 2 min
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:
- The worker queries all routes for the account.
- Routes are matched against the event's
source_idandevent_type. - A route matches if:
- Its
source_idmatches the event's source (or isnull— catch-all for all sources). - Its
event_type_patternmatches the event'sX-Event-Typeheader (or isnull— catch-all for all event types).
- Its
- 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/routesAuthentication: 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/routesAuthentication: 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 .