> ## Documentation Index
> Fetch the complete documentation index at: https://supahooks.ar27111994.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Forward webhook traffic to a downstream server

> Automatically POST every captured request to a destination URL with retries and circuit breaker protection, keeping your downstream server in sync.

When `forwardUrl` is configured, every request captured by your webhook endpoint is automatically forwarded to that destination as a `POST` request. This lets you route live traffic to another server — such as a staging environment, a data pipeline, or a second integration — while still capturing and inspecting the full event in the debugger.

Forwarding happens automatically on every capture. If you want to resend a specific historical event to a target on demand, use [replay](/features/replay) instead.

## Configuration

Set `forwardUrl` in your actor input to enable forwarding:

```json theme={null}
{
  "forwardUrl": "https://example.com/ingest",
  "forwardHeaders": true,
  "maxForwardRetries": 3
}
```

<ParamField query="forwardUrl" type="string">
  Destination URL that receives a copy of every captured request. Leave unset to disable forwarding.
</ParamField>

<ParamField query="forwardHeaders" type="boolean" default="true">
  When enabled, the original request headers are included in the forwarded request. Disable this to send only `Content-Type` and `Content-Length`, keeping the outbound request clean.
</ParamField>

<ParamField query="maxForwardRetries" type="integer" default="3">
  Maximum retry attempts for a failed forward request. Accepted range: 0–10.
</ParamField>

## Circuit breaker protection

To prevent a slow or failing downstream server from backing up your captures, forwarding uses a circuit breaker. After **5 consecutive failures**, the circuit trips and forwarding is paused for **30 seconds**. During that window, incoming webhook requests are still captured normally — forwarding resumes automatically when the pause expires.

## Self-referential loop protection

Pointing `forwardUrl` at one of your own webhook endpoints would create an infinite loop. The runtime detects this and returns `422 Unprocessable Entity` instead of forwarding the request.

## Forwarding vs. replay

|          | Forwarding                                | Replay                                |
| -------- | ----------------------------------------- | ------------------------------------- |
| Trigger  | Automatic on every capture                | Manual, per event                     |
| Target   | Fixed `forwardUrl`                        | Any URL you specify at call time      |
| Retries  | `maxForwardRetries`                       | `replayMaxRetries`                    |
| Use case | Mirror all traffic to a downstream server | Resend a specific event to test a fix |

## Pairing with alerts

Combine forwarding with `alertOn` to get notified when delivery to your downstream server fails:

```json theme={null}
{
  "forwardUrl": "https://example.com/ingest",
  "forwardHeaders": true,
  "maxForwardRetries": 3,
  "alertOn": ["error", "5xx"]
}
```

<Warning>
  Generated webhook URLs are public unless you enable `authKey`, `allowedIps`, or signature verification. When forwarding to a sensitive downstream server, make sure your endpoint is secured before pointing production traffic at it.
</Warning>