Routing strategies overview

import { Aside } from ‘@astrojs/starlight/components’

When a webhook arrives at your Hookman endpoint, the proxy needs to decide which deployment to forward it to. This decision is called routing.

Hookman evaluates routing strategies in a fixed priority order:

1. Header routing       (fastest — no body parsing needed)
2. Query param routing  (fast — URL only)
3. Payload routing      (requires parsing JSON body)
4. Active deployment    (manual switch fallback)

The first strategy that resolves a matching deployment wins. If none match, Hookman returns 422 no_route_resolved.

Configuring routing

Set up routing in your project settings (dashboard or API). You can configure multiple strategies simultaneously — they’re evaluated in the order above.

Project settings → Routing
  ☐ Routing header:      x-hookman-branch
  ☐ Query parameter:     branch
  ☐ Payload path:        metadata.branch

Leave all three blank to use manual switch only.

Strategy comparison

	Header	Query param	Payload	Manual switch
Requires body parse	No	No	Yes	No
Caller must include routing key	Yes	Yes	Yes	No
Works with any provider	Depends	Depends	Depends	Yes
Fully automatic	Yes	Yes	Yes	No

Manual switch

The simplest strategy. You explicitly set which deployment receives webhooks by marking it as active. No routing key needed from the caller.

Good for: solo developers, prototyping, any situation where you want direct control.

Manual switch documentation →

Header routing

Hookman reads a specific request header and matches its value against your deployment labels.

Incoming header:  x-hookman-branch: feature/checkout
Deployment label: feature/checkout
→ Routes to that deployment

Good for: internal tooling, platforms that let you inject custom headers, webhook forwarders.

Header routing documentation →

Payload routing

Hookman parses the JSON body and reads a value at a dot-notation path.

// Incoming body
{ "metadata": { "branch": "feature/checkout" } }

// Config: payload path = "metadata.branch"
// Resolved value: "feature/checkout"
// → Routes to matching deployment

Good for: platforms that include environment metadata in their payload (some CI platforms, internal event buses, custom webhook senders).

Payload routing requires Hookman to read and parse the request body. The body is still forwarded unchanged to your deployment — parsing is read-only. However, if your payload routing is misconfigured, Hookman parses a large body unnecessarily. Use header routing where possible.

Payload routing documentation →

Fallback behaviour

If the configured routing strategy finds a key but no matching deployment:

• Hookman does not fall through to the next strategy
• Hookman returns 422 no_route_resolved with the unmatched key in the response body

This is intentional — a key was found but didn’t match, which is likely a misconfiguration rather than a legitimate fallback case.

If no routing key is found at all (header absent, payload path resolves null), Hookman falls through to the next configured strategy, and ultimately to the active deployment.

Combining strategies

You can configure all three strategies simultaneously. This is useful when you have a mix of callers — some include a header, some don’t:

Header:  x-hookman-branch  → routes specific callers by header
Payload: metadata.branch   → routes callers that embed branch in payload
Active:  main              → everything else goes to main