Webhook Guides

Webhook Paths Integration

Webhook paths are easy to overlook until a provider preserves a subpath, a route filter misses traffic, or a local tunnel delivers to the wrong receiver route. FastHook stores the inbound request path, lets filters match paths, and controls destination path behavior separately from source ingress.

Use this guide when your integration depends on URLs such as /stripe/webhook,/github/webhook, /orders, or /webhooks/provider, and you need to know where that path is captured, matched, forwarded, or replaced.

Webhook request anatomy showing method, source URL, query, headers, path, JSON body, and response.
The inbound request path is request evidence. Destination path behavior is controlled later by the destination and route.

Three different path concepts

ConceptExampleWhere to configure or inspect
Inbound request path/stripe/webhookStored on the request as path.
Path filter{"$starts_with":"/stripe"}Connection filter rule target path.
Destination path behaviorpath_forwarding_disabled or config.pathDestination config for HTTP, CLI, and mock delivery.

Capture the request path

When a sender calls a FastHook source URL with a path, FastHook stores that path with the request. You can inspect it with include=data, use it in filters, and replay the original request through current routing when route behavior changes.

Send a request with a path
curl -X POST "https://hook-xxxxxx.fasthook.io/stripe/webhook?env=staging" \
  -H "Content-Type: application/json" \
  -H "X-Event-Type: invoice.paid" \
  -d '{"id":"evt_42","type":"invoice.paid"}'
Stored request path
{
  "id": "req_01jv8c3m7b2p4q9x6r5t1n0k8s",
  "status": "accepted",
  "data": {
    "path": "/stripe/webhook",
    "query": "env=staging",
    "parsed_query": {
      "env": "staging"
    },
    "method": "POST"
  }
}

Route by path filters

The filter path target matches the full request path string. Use exact matches for stable provider routes and prefix or regex matches when several provider paths should share one branch.

Exact path filter
{
  "type": "filter",
  "path": "/stripe/webhook"
}
Multiple provider paths
{
  "type": "filter",
  "path": {
    "$regex": "^/(stripe|github)/webhook$"
  }
}
Prefix path filter
{
  "type": "filter",
  "path": {
    "$starts_with": "/orders"
  }
}

Forward or omit inbound paths

HTTP destinations can keep path forwarding enabled when the receiver expects the inbound provider path to stay visible. Disable path forwarding when the destination URL already contains the receiver route or when all provider paths should land on one fixed endpoint.

HTTP destination with path forwarding setting
{
  "name": "Billing API",
  "type": "HTTP",
  "config": {
    "url": "https://api.example.com/webhooks",
    "http_method": "POST",
    "path_forwarding_disabled": false,
    "auth_type": "FASTHOOK_SIGNATURE",
    "auth": {}
  }
}

CLI destination paths

CLI destinations store a cloud-side config.path. The local host and port come from the active tunnel session. This keeps the route stable while each developer chooses a local target at runtime.

CLI path mapping
CLI destination path: /webhooks/orders
fasthook-cli target:   http://localhost:8080
local request URL:     http://localhost:8080/webhooks/orders

CLI destination path: /
fasthook-cli target:   http://localhost:8080
local request URL:     http://localhost:8080/
Create CLI destination path
curl -X POST "https://api.fasthook.io/v1/destinations" \
  -H "Authorization: Bearer $FASTHOOK_API_KEY" \
  -H "x-team-id: $FASTHOOK_TEAM_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Local orders receiver",
    "type": "CLI",
    "config": {
      "path": "/webhooks/orders",
      "http_method": "POST"
    }
  }'

Debug wrong path deliveries

  • No routed event: inspect the stored request path and compare it with the connection path filter.
  • Receiver 404: inspect the attempt requested_url and the destination path config.
  • Local tunnel wrong route: compare CLI destination config.path with the local server route.
  • Provider changed URL: check whether the new path should be filtered, forwarded, or normalized.
  • Replay changed behavior: request replay uses current routing, so path filters can create different events after configuration changes.

Path integration checklist

  • Decide whether provider subpaths are meaningful routing inputs or just transport details.
  • Use exact path filters for stable routes and regex filters only when several paths intentionally share a branch.
  • Keep destination URL paths and inbound path forwarding from accidentally duplicating route segments.
  • For CLI destinations, store only the route path in FastHook and pass host/port through the tunnel.
  • Inspect request path and attempt requested_url before changing application code.

Related guides