Routes

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

Overview

A route defines:

• Which source it listens to
• Which destinations receive the webhook
• What transforms to apply (optional)
• What filters to use (optional)

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

Creating a Route

Required Fields

Field	Description
name	Human-readable name
sourceId	The source to listen to
destinationIds	Array of destination IDs

Optional Fields

Field	Description
description	Optional description
transformId	Transform to apply
filterId	Filter to evaluate
enabled	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": "src_abc123",
    "destinationIds": ["dst_xyz789"]
  }'

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": "src_abc123",
    "destinationIds": ["dst_xyz789"],
    "transformId": "tfm_format123"
  }'

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": "src_abc123",
    "destinationIds": ["dst_xyz789"],
    "filterId": "flt_pushonly456"
  }'

Multiple Destinations

A single route can deliver to multiple destinations simultaneously:

{
  "name": "GitHub to Multiple",
  "sourceId": "src_abc123",
  "destinationIds": [
    "dst_slack",
    "dst_discord",
    "dst_database"
  ]
}

All destinations receive the same payload (after transforms are applied).

Route Processing Order

When a webhook arrives:

1. Source receives webhook
2. Signature verification (if configured on source)
3. Find matching routes for the source
4. For each enabled route:
   1. Apply transform (if configured)
   2. Evaluate filter (if configured)
   3. If filter passes (or no filter): Queue delivery to destinations
5. 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 '{
    "enabled": 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:

GitHub Source ──▶ Route ──┬──▶ Slack
                          ├──▶ Discord
                          ├──▶ Database
                          └──▶ 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

1. Name routes descriptively: Include source and destination in the name (e.g., "GitHub to Slack")

2. Use filters wisely: Filter early to reduce unnecessary deliveries

3. Test before enabling: Use the Testing page to verify transforms and filters work correctly

4. Monitor route health: Check the analytics for success rates per route

5. Disable instead of delete: When troubleshooting, disable routes instead of deleting them

Troubleshooting

Webhooks not being delivered

1. Verify the route is enabled
2. Check if the source is enabled
3. Verify destination(s) are enabled
4. Check if a filter is blocking events
5. Review transform for errors

Duplicate deliveries

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