Webhook Guides

Webhook Gateway

A webhook gateway is the operational layer between webhook producers and your application receivers. Instead of pointing every provider directly at app code, providers send events to a stable gateway endpoint first.

FastHook acts as that gateway: it receives webhook requests through sources, verifies source authentication, stores request evidence, routes events through connections, delivers them to destinations, and keeps retries and replay scoped to recorded events.

Webhook gateway resource model with source, connection, destination, request, event, and attempt records.
A webhook gateway separates ingress, routing, delivery, and recovery so one provider request can be inspected before and after every branch.

What a webhook gateway does

  • Gives providers stable webhook URLs while your services deploy, restart, or move environments.
  • Verifies signatures, API keys, Basic Auth, provider presets, and allowed HTTP methods at ingress.
  • Routes accepted events by headers, body fields, query params, paths, provider metadata, or rules.
  • Stores request, event, attempt, response body, retry, and replay evidence in one operational trail.
  • Lets operators retry one failed event or replay accepted requests after route changes.

When a gateway is worth it

A direct webhook endpoint is fine for a tiny integration with one sender and one receiver. A gateway becomes useful when several providers share a receiver, one provider needs to fan out to several destinations, or the business impact of a missed event is high enough that engineers need a recovery path beyond provider logs.

The strongest signal is operational pain: support asks whether a payment event arrived, finance needs to replay a failed reconciliation window, or a receiver deployment caused provider retries to pile up. A gateway gives those questions a durable event trail instead of a hunt across application logs.

Gateway vs direct webhook endpoint

ConcernDirect endpointWebhook gateway
Provider URLChanges with app infrastructure.Stable source URL per provider or environment.
DebuggingStarts in app logs after delivery.Starts at request capture, before routing.
RecoveryDepends on provider redelivery or custom scripts.Retries and replay use recorded events.
Fan-outUsually hand-coded in each receiver.Branch-local connections route to multiple destinations.

Create a gateway source

Create gateway source
curl -X POST "https://api.fasthook.io/v1/sources" \
  -H "Authorization: Bearer $FASTHOOK_API_KEY" \
  -H "x-team-id: $FASTHOOK_TEAM_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production webhook gateway",
    "type": "WEBHOOK",
    "config": {
      "auth_type": "HMAC",
      "auth": {
        "secret": "provider_webhook_secret",
        "signature_header": "x-provider-signature"
      },
      "allowed_http_methods": ["POST"]
    }
  }'

Gateway routing model

FastHook models the gateway as source to connection to destination. The source owns the public URL and provider trust boundary. The connection owns routing rules, transformations, retry policy, pause state, and branch identity. The destination owns the receiver URL, outbound authentication, delivery method, rate limit, and delivery attempt evidence.

That separation matters during incidents. If provider auth fails, fix the source. If the wrong branch receives the event, inspect connection filters. If the app returns 500, inspect destination attempts and retry the failed event after the receiver is fixed.

Common gateway mistakes

  • Using one catch-all source for several providers that have different signature schemes.
  • Forwarding every event to every receiver instead of using branch-local filters.
  • Retrying a broad request window when only one destination attempt failed.
  • Ignoring idempotency because the gateway can replay events safely from its side.
  • Changing the provider URL during incidents instead of fixing routes behind a stable source URL.

Related guides