Webhook Guides

Webhook Relay

A webhook relay receives requests on one public URL and forwards accepted events to another destination. It is useful when the receiver moves between local, staging, and production, or when a provider needs one stable URL while your backend changes behind it.

FastHook works as a relay with source URLs, HTTP destinations, CLI destinations for localhost, routing filters, path forwarding, retries, replay, and request evidence. The relay is not just a blind proxy; it keeps enough state to debug and recover failed deliveries.

Relay patterns

PatternDestinationUse case
Production relayHTTP destinationProvider to deployed API with retries and evidence.
Local relayCLI destinationProvider to localhost during development.
Audit relayGoogle Sheet or GmailProvider event to human review workflow.
Fan-out relayMultiple connectionsOne source to several downstream services.

Create an HTTP relay destination

HTTP destination
curl -X POST "https://api.fasthook.io/v1/destinations" \
  -H "Authorization: Bearer fhp_xxx" \
  -H "x-team-id: tm_3b5335b627084a838b" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production receiver",
    "type": "HTTP",
    "config": {
      "url": "https://api.example.com/webhooks/provider",
      "http_method": "POST",
      "path_forwarding_disabled": false,
      "auth_type": "FASTHOOK_SIGNATURE",
      "auth": {}
    }
  }'

Why relay instead of direct delivery

  • Provider URLs stay stable while receiver infrastructure changes.
  • Local development can receive real provider events without exposing a laptop directly.
  • Failures can be inspected at request, routing, and destination stages.
  • Retries and replay can target one failed branch instead of asking the provider to resend everything.

Relay safety

A relay can redeliver events, so the receiver still needs idempotency. Use provider event ids or business object ids before applying side effects, and test duplicate delivery before enabling bulk replay.

Path forwarding

Some providers send meaningful paths, for example separate endpoints for orders, billing, or tenant routing. FastHook can preserve request path context and forward destination paths when that is useful, or you can disable path forwarding when the receiver expects one fixed URL.

Path decisions should be explicit. A relay that silently changes paths makes debugging harder because the provider dashboard, gateway logs, and receiver logs no longer describe the same request.

  • Keep source URLs stable and move receiver paths behind destination configuration.
  • Use path filters when one source must accept several provider callback paths.
  • Disable path forwarding when the destination route is a single fixed webhook handler.
  • Inspect captured request paths before replaying a route migration.

Local to production handoff

A relay is especially helpful when the same provider event needs to be tested locally and then sent to production. Start with a CLI destination, prove the receiver behavior, then switch the connection target or create a parallel production connection once the local handler is stable.

Related guides