Routing And Destinations

Routing is where a single webhook becomes a small event gateway. Hooksbase keeps one default destination, lets you add named destinations, and then evaluates an ordered route-to-one rule set that chooses exactly one destination per accepted delivery.

Routing model

The routing model is intentionally narrow:

• exactly one default destination per webhook
• optional named destinations for cutovers, canaries, or sink-type changes
• first enabled matching rule wins by ascending priority
• unmatched traffic falls back to the default destination
• no fan-out, no header mutation, and no URL rewriting from the routing layer

Accepted deliveries persist the resolved destination snapshot. Retries, replay, DLQ re-drive, and bulk replay keep using that saved destination config even after the live routing table changes.

Auth model

Destinations

Every webhook starts with one default destination. The current destination types are:

• webhook
• aws_sqs
• aws_eventbridge
• gcp_pubsub
• object_storage

Operational rules:

• the default destination cannot be deleted
• deleting a destination that is still referenced by a routing rule returns 409
• non-webhook destination types are Pro+ features
• paused or missing resolved destinations fail ingest admission with 400

hooksbase webhooks routing update wh_123 --file ./routing.json

{
  "defaultDestinationId": "dest_default",
  "rules": [
    {
      "name": "priority-orders",
      "enabled": true,
      "priority": 1,
      "matchMode": "all",
      "destinationId": "dest_orders",
      "conditions": [
        { "source": "headers.x-tenant", "operator": "eq", "value": "acme" },
        { "source": "payload.kind", "operator": "eq", "value": "order.created" }
      ]
    }
  ]
}

curl https://api.hooksbase.com/v1/webhooks/wh_123/routing \
  -X PUT \
  -H "Authorization: Bearer swk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "defaultDestinationId": "dest_default",
    "rules": [
      {
        "name": "priority-orders",
        "enabled": true,
        "priority": 1,
        "matchMode": "all",
        "destinationId": "dest_orders",
        "conditions": [
          { "source": "headers.x-tenant", "operator": "eq", "value": "acme" },
          { "source": "payload.kind", "operator": "eq", "value": "order.created" }
        ]
      }
    ]
  }'

Route-to-one rules

Each rule compares condition sources against literal values. The supported sources are:

• contentType — the request's Content-Type header
• headers.<name> — any inbound header, lower-cased
• payload.<path> — dot-path into parsed JSON, including numeric array indexes (e.g. payload.items.0.sku)
• provider.name, provider.sourceId, provider.eventType, and provider.verified — normalized metadata from a configured provider pack

Supported operators:

• eq, neq — strict equality
• contains, starts_with — substring on strings
• exists — value is present (no value needed)
• in — value appears in the array supplied as value
• gt, gte, lt, lte — numeric comparison

Other limits that matter:

• up to 200 rules per webhook
• up to 25 conditions per rule
• matchMode is all (AND) or any (OR)
• omitted priorities default from submitted array order, but final priorities must still be unique

Routing always evaluates the original source payload before any payload transform runs. If a rule references payload.<path> and the body is not JSON, the rule simply does not match.

Related routes

• GET /v1/webhooks/{id}/destinations
• POST /v1/webhooks/{id}/destinations
• PATCH /v1/webhooks/{id}/destinations/{destinationId}
• DELETE /v1/webhooks/{id}/destinations/{destinationId}
• GET /v1/webhooks/{id}/routing
• PUT /v1/webhooks/{id}/routing

Common mistakes

• Expecting routing to fan out to multiple destinations. Routing is route-to-one only.
• Forgetting that the first matching enabled rule wins, even if a later rule is more specific.
• Assuming replay will use today's routing table instead of the saved destination snapshot.
• Pointing destinations back at Hooksbase ingest or form endpoints instead of a real downstream target.