Routes

Routes connect sources to destinations, optionally applying transforms and filters.

Overview

A route defines:

Which source it listens to
Which destination receives the webhook
What transforms to apply (optional)
What filters to use (optional)

Source ──▶ Route ──▶ [Transform] ──▶ [Filter] ──▶ Destination

Creating a Route

Required Fields

Field	Description
`name`	Human-readable name
`sourceId`	The source to listen to
`destinationId`	The destination to deliver to

Optional Fields

Field	Description
`transformId`	Transform to apply
`filterId`	Filter to evaluate
`isActive`	Whether the route is active (default: true)

Example: Creating a Route

Basic Route

curl -X POST https://api.hookbase.app/api/routes \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub to Slack",
    "sourceId": "11111111-1111-4111-8111-111111111111",
    "destinationId": "22222222-2222-4222-8222-222222222222"
  }'

Route with Transform

curl -X POST https://api.hookbase.app/api/routes \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub to Slack (Formatted)",
    "sourceId": "11111111-1111-4111-8111-111111111111",
    "destinationId": "22222222-2222-4222-8222-222222222222",
    "transformId": "88888888-8888-4888-8888-888888880006"
  }'

Route with Filter

curl -X POST https://api.hookbase.app/api/routes \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub Push Only",
    "sourceId": "11111111-1111-4111-8111-111111111111",
    "destinationId": "22222222-2222-4222-8222-222222222222",
    "filterId": "77777777-7777-4777-8777-777777770017"
  }'

Multiple Destinations

A route delivers to exactly one destination. To send one source's events to several destinations, create one route per destination — all pointing at the same sourceId:

{
  "routes": [
    {
      "name": "GitHub to Slack",
      "sourceId": "11111111-1111-4111-8111-111111111111",
      "destinationId": "22222222-2222-4222-8222-22222222002c"
    },
    {
      "name": "GitHub to Discord",
      "sourceId": "11111111-1111-4111-8111-111111111111",
      "destinationId": "22222222-2222-4222-8222-22222222001d"
    },
    {
      "name": "GitHub to Database",
      "sourceId": "11111111-1111-4111-8111-111111111111",
      "destinationId": "22222222-2222-4222-8222-22222222001c"
    }
  ]
}

POST /api/routes/bulk accepts that body and creates up to 50 routes in one request. Calling POST /api/routes once per destination gives the same result.

Every matching route runs for each event, so all three destinations receive the same payload — but each route has its own transform, filter, retry state, and circuit breaker, so you can shape and pause them independently.

Warning

failoverDestinationIds is not fan-out. Failover destinations are only tried after the route's primary destination has failed failoverAfterAttempts times. Use separate routes to deliver to several destinations at once.

Route Processing Order

When a webhook arrives:

Source receives webhook
Signature verification (if configured on source)
Find matching routes for the source
For each enabled route:
1. Apply transform (if configured)
2. Evaluate filter (if configured)
3. If filter passes (or no filter): Queue delivery to the route's destination
Deliver to destinations asynchronously

Managing Routes

List Routes

curl https://api.hookbase.app/api/routes \
  -H "Authorization: Bearer whr_your_api_key"

Get Route Details

curl https://api.hookbase.app/api/routes/{routeId} \
  -H "Authorization: Bearer whr_your_api_key"

Update Route

curl -X PATCH https://api.hookbase.app/api/routes/{routeId} \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "isActive": false
  }'

Delete Route

curl -X DELETE https://api.hookbase.app/api/routes/{routeId} \
  -H "Authorization: Bearer whr_your_api_key"

Common Patterns

Fan-out

One source to many destinations — one route each:

GitHub Source ──┬──▶ Route ──▶ Slack
                ├──▶ Route ──▶ Discord
                ├──▶ Route ──▶ Database
                └──▶ Route ──▶ Analytics

Content-based Routing

Multiple routes from one source with different filters:

GitHub Source ──▶ Route (push filter) ──▶ CI/CD
              ──▶ Route (PR filter) ──▶ Review System
              ──▶ Route (issue filter) ──▶ Issue Tracker

Transform Pipeline

Apply different transforms for different destinations:

Stripe Source ──▶ Route (Slack transform) ──▶ Slack
              ──▶ Route (DB transform) ──▶ Database

Best Practices

Name routes descriptively: Include source and destination in the name (e.g., "GitHub to Slack")
Use filters wisely: Filter early to reduce unnecessary deliveries
Test before enabling: Use the Testing page to verify transforms and filters work correctly
Monitor route health: Check the analytics for success rates per route
Disable instead of delete: When troubleshooting, disable routes instead of deleting them

Troubleshooting

Webhooks not being delivered

Verify the route is enabled
Check if the source is enabled
Verify destination(s) are enabled
Check if a filter is blocking events
Review transform for errors

Duplicate deliveries

Check if multiple routes are configured for the same source/destination pair
Verify your application handles idempotency