A forwarder is a destination attached to a bucket. When a bucket receives a webhook, each active forwarder decides where that request should be delivered and how delivery should behave. You can attach multiple forwarders to a queued bucket or exactly one forwarder to a proxy bucket.
Destination types#
Pick the forwarder type that matches where your webhook traffic should land. The type is a creation-time decision: you cannot change an external forwarder to internal, or vice versa, after it has been created.
Sends webhook requests to a public http or https endpoint, such as a production service, staging environment, or partner API.
Holds events for a connected CLI session, then delivers them to a local destination such as localhost:3000. Use this type during local development.
Forwarder type is set at creation and cannot be changed. If you need to switch from external delivery to CLI delivery, or the reverse, create a new forwarder with the correct type.
Path modes#
Path mode controls whether Repost preserves the original incoming request path or always sends traffic to a single fixed URL.
Repost treats your configured destination as a base URL and appends the original request path to it.
| Incoming request | Forwarded to |
|---|---|
/webhooks/stripe | https://api.example.com/webhooks/stripe |
/webhooks/github | https://api.example.com/webhooks/github |
Use transparent mode when your server already handles multiple provider paths and you want those paths preserved end-to-end.
Create a forwarder#
You can create a forwarder when setting up a bucket for the first time, or later from the bucket's Forwarders page.
Choose a name that describes the destination, such as production-api, local-webhooks, or analytics-worker. Names must be unique within a bucket.
Select External to target a public HTTP endpoint. Select Internal to target a developer machine through the Repost CLI.
Select Transparent to preserve the provider path. Select Locked to send all traffic to one fixed destination URL.
Choose http or https from the protocol selector, then enter host[:port][/path] without the protocol prefix. Internal forwarders default to http.
The default timeout is 20000 ms. You can set any value between 5000 and 60000 ms in steps of 1000 ms.
Queued buckets expose retry and rate-limit controls during creation. Proxy buckets hide those controls because the provider connection is waiting on a single synchronous destination response.
Bucket mode rules#
The bucket's response mode determines which forwarder controls are available to you.
Supports multiple forwarders, retry configuration, replay operations, and per-forwarder rate limits.
Supports exactly one forwarder. Retry configuration and rate limiting are not available because one destination owns the upstream response.
A proxy bucket rejects a second forwarder and rejects any retry or rate-limit settings. Create a queued bucket when you need multiple destinations or asynchronous delivery controls.
Delivery controls#
These values are stored on the forwarder. All of them can be adjusted from the forwarder's settings page after creation, subject to the bucket mode rules above.
Timeout
Allowed range: 5000–60000 ms in 1000 ms steps. Default: 20000 ms. Repost marks a delivery attempt as timed out if the destination does not respond within this window.
Retries (queue buckets only)
Allowed range: 0–3. Default at creation: 3. Set retries to 0 to disable them. Repost retries connection failures and responses with status 408, 429, or 5xx. All other 4xx responses are treated as final.
Retry delay (queue buckets only)
Allowed range: 5000–60000 ms. Default: 15000 ms. This sets the initial retry window. Retry waits use full jitter: Repost picks a delay between 0 and the current window, floors it at 1000 ms, then grows the window by the backoff multiplier after each attempt.
Backoff multiplier (queue buckets only)
Allowed range: 0.5x–3.0x. Default: 2.0x. The retry window is multiplied by this value after each failed attempt.
Max retry delay (queue buckets only)
Allowed range: 60000–1800000 ms. Default: 900000 ms. The retry window is capped at this value regardless of how many times the backoff multiplier is applied.
Rate limit (queue buckets only)
Off by default. When enabled, delivery is capped at 5–500 requests per second in steps of 5.
Retry waits use full jitter. Repost picks a delay between 0 and the current retry window, floors it at 1000 ms, then grows the window by the backoff multiplier until it is capped by the max retry delay.
External target restrictions#
When you create an external forwarder, Repost validates the destination before saving. The following targets are blocked:
localhostand loopback addresses- Private or reserved IP ranges
- Single-label hostnames (e.g.
myserverwith no domain) - Internal-only hostnames
- Hostnames that resolve via DNS to any of the above blocked addresses
Common errors#
Name is already taken
Forwarder names must be unique within a bucket. Choose a different name or rename the existing forwarder first.
Proxy bucket already has a forwarder
Proxy buckets support exactly one forwarder. To add a second destination, convert your setup to a queued bucket.
Retry or rate limit rejected for proxy
Proxy forwarders do not support retry configuration or rate limiting. These controls are available only on queued bucket forwarders.
External target is not allowed
The destination you entered points to a blocked address. Use a public hostname that resolves to a non-private IP address.
Forwarder type cannot be changed
Type is set at creation and is immutable. Create a new forwarder with the correct type instead.
Delete is blocked by an active replay
A forwarder cannot be deleted while a replay job is pending, estimating, processing, or paused. Cancel the replay or wait for it to complete before deleting.