Webhook Guides

Webhook URL

A webhook URL is the HTTP address another system calls when an event happens. In FastHook, the provider-facing webhook URL is a source URL, and the app-facing receiver URL is a destination URL.

Keeping those two URLs separate makes it easier to rotate receivers, test locally, add authentication, inspect failures, and replay events without changing the provider configuration every time.

Webhook URL boundaries showing provider source URL and application destination URL.
A source URL receives provider traffic. A destination URL receives routed FastHook delivery.

Source URL vs destination URL

  • Source URL: the public webhook URL pasted into Stripe, GitHub, Linear, or another sender.
  • Destination URL: your API endpoint that receives routed events after FastHook accepts them.
  • Path: the request path can be used for route filters or forwarded to the destination.
  • Auth: source auth protects ingress; destination auth helps your receiver trust FastHook.

Good webhook URL design

A good webhook URL is stable, environment-specific, and easy to audit. Do not reuse one production URL for local testing, staging, and real customer traffic. Keep separate source URLs per environment and provider so signature secrets, rejected requests, replay windows, and provider dashboards stay understandable.

The URL should also survive receiver changes. If your application endpoint moves from/api/webhooks/orders to /api/events/orders, the provider-facing source URL can stay the same while the destination URL changes behind FastHook.

Create a webhook URL

Create source URL
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": "Public webhook URL",
    "type": "WEBHOOK",
    "config": {
      "auth_type": null,
      "allowed_http_methods": ["POST"]
    }
  }'

Path forwarding example

Some providers call paths such as /webhooks/orders or /events/github. FastHook can keep the original request path available for filters and, when enabled on the destination, forward that path to the receiver. That makes one source URL support several route families without losing debugging context.

Create destination with path forwarding
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": "receiver-api",
    "type": "HTTP",
    "config": {
      "url": "https://api.example.com",
      "http_method": "POST",
      "path_forwarding_disabled": false
    }
  }'

Common webhook URL mistakes

  • Using a localhost URL in a provider dashboard without a tunnel.
  • Changing the provider URL instead of changing the destination behind the gateway.
  • Mixing staging and production traffic in one source URL.
  • Putting secrets in query strings instead of using source authentication or signed payloads.
  • Forgetting that provider retries can call the same URL multiple times.

Webhook URL checklist

  1. Create one source URL per provider and environment.
  2. Paste the source URL into the provider dashboard, not the receiver URL.
  3. Use the provider's signing secret or auth header on the source.
  4. Connect the source to a destination URL owned by your app.
  5. Send a test event and confirm request, event, and attempt records exist.
  6. Record the source id and destination id in your integration runbook.

If a teammate asks for "the webhook URL", clarify which side they mean. Providers need the source URL. Receiver owners usually need the destination URL. Incident responders need both, plus the connection that routes between them.

Related guides