Guide

Webhook Proxy

Webhook proxy mode puts FastHook between a webhook producer and your upstream API. The source accepts the incoming request, stores the inbound evidence, forwards the same request to a configured target URL, captures the upstream response, and returns that upstream response to the caller.

This is different from the default async gateway path. A normal source acknowledges quickly and routes destinations in the background. A proxy source waits for the upstream API because the caller should receive the upstream status, headers, and body.

Use proxy mode when you need to inspect both sides of the exchange: provider request, upstream response, latency, response body preview, routed event branches, and later destination attempts.

How Proxy Mode Maps To FastHook

Proxy mode is still a source. It does not replace connections, destinations, retries, replay, request bins, or transformations. It changes only the source response behavior for that source URL.

The inbound request is captured before the upstream call is made. Active connections can still route the accepted request to destinations, so proxy traffic can be archived, alerted, transformed, or delivered to operational tools.

  • Source URL remains the public entry point.
  • config.mode is proxy.
  • config.proxy.target_url is the upstream API base URL.
  • config.proxy.path_forwarding controls whether incoming paths are appended to the target path.
  • Request Trace shows the inbound request, proxy exchange, routed events, transformations, and attempts.
Proxy source path
Provider or client
  -> FastHook proxy source URL
  -> request captured as req_xxx
  -> upstream API called synchronously
  -> upstream response stored as proxy_exchange
  -> upstream response returned to caller
  -> optional connections route events asynchronously

Create A Proxy Source

In the dashboard, create or edit a source and enable Proxy upstream. Set the target URL, timeout, response capture limit, and HTTP methods that the source should accept.

Through the API, set config.mode to proxy and provide config.proxy. FastHook validates the target URL and rejects localhost, private IP ranges, and metadata hosts.

Proxy source config
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": "stripe-to-api-proxy",
    "type": "WEBHOOK",
    "config": {
      "mode": "proxy",
      "allowed_http_methods": ["HEAD", "GET", "POST", "PUT", "PATCH", "DELETE"],
      "proxy": {
        "target_url": "https://api.example.com/webhooks",
        "path_forwarding": true,
        "timeout_ms": 10000,
        "response_capture_limit_bytes": 65536
      }
    }
  }'

Path And Query Forwarding

When path_forwarding is true, FastHook appends the incoming path to the target URL path. Query parameters from the incoming request are appended to the target URL query.

For example, if the target URL is https://api.example.com/hooks and the caller sends /stripe/invoice?mode=live, the upstream request goes to https://api.example.com/hooks/stripe/invoice?mode=live.

  • Use path_forwarding true when one source should proxy several upstream routes.
  • Use path_forwarding false when every inbound request should go to the exact target path.
  • Set allowed_http_methods explicitly when the upstream API accepts GET, HEAD, or DELETE.

What Gets Captured

FastHook stores the original inbound request in the normal request/event_data path. Proxy-specific response evidence is stored separately as a proxy exchange linked to the same request id.

The response body is capped by response_capture_limit_bytes. The full upstream response is still streamed back to the caller; the cap only limits what FastHook stores for inspection.

  • Upstream target URL and method.
  • Upstream response status.
  • Upstream response headers.
  • Response body preview and truncation flag.
  • Response latency.
  • Proxy fetch errors such as timeout or network failure.

Inspect A Proxy Request

Open Requests, select the request, and click Trace. The trace page shows the inbound request first, then the proxy upstream block with response status, target URL, response headers, body preview, and latency.

If the same request also routed through connections, the trace continues into routed events, transformations, destination attempts, retries, and failed receiver responses.

Trace response shape
GET /v1/requests/req_abc123/trace

{
  "request": { "...": "..." },
  "proxy_exchange": {
    "target_url": "https://api.example.com/webhooks/stripe",
    "response_status": 200,
    "response_latency": 84,
    "response_body_truncated": false
  },
  "events": [],
  "attempts": [],
  "timeline": []
}

When Proxy Mode Is Useful

  • You need to debug upstream 400, 401, 404, 429, or 500 responses without asking the provider to resend blindly.
  • You want ngrok-style inspection for deployed webhook traffic, not only localhost traffic.
  • You are migrating a provider webhook from a direct API endpoint to FastHook and want the provider to keep receiving the same upstream response.
  • You need a stable entry point that can both forward and route the same traffic to logs, alerts, storage, or human destinations.

Limits And Safety

Proxy mode is synchronous, so the caller waits for the upstream API. Keep upstream handlers fast and use timeout_ms to avoid tying provider delivery to a stuck receiver.

FastHook strips hop-by-hop and Cloudflare control headers before forwarding. It adds FastHook request/source headers to the upstream request so the receiver can correlate traffic back to the trace page.

  • Do not point proxy targets at private networks, localhost, or metadata services.
  • Use source authentication when the proxy URL should not be public.
  • Keep response capture limits small enough for fast trace loading.
  • Use normal destinations for async retries; proxy mode does not retry upstream before returning to the caller.

Next