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.webhookrelay.com/api/organizations/{orgId}/routes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub to Slack",
    "sourceId": "src_abc123",
    "destinationIds": ["dst_xyz789"]
  }'

Route with Transform

curl -X POST https://api.webhookrelay.com/api/organizations/{orgId}/routes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -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.webhookrelay.com/api/organizations/{orgId}/routes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -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.webhookrelay.com/api/organizations/{orgId}/routes \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Route Details

curl https://api.webhookrelay.com/api/organizations/{orgId}/routes/{routeId} \
  -H "Authorization: Bearer YOUR_TOKEN"

Update Route

curl -X PATCH https://api.webhookrelay.com/api/organizations/{orgId}/routes/{routeId} \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

Delete Route

curl -X DELETE https://api.webhookrelay.com/api/organizations/{orgId}/routes/{routeId} \
  -H "Authorization: Bearer YOUR_TOKEN"

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