Response behavior is the contract between the webhook sender and the bucket URL. You choose the response mode when you create the bucket, and you tune the mode-specific fields (status code, body, or timeout) from settings at any time after creation. The mode itself cannot be changed once the bucket exists.
Response mode is permanent#
Every bucket is either a Queue bucket or a Proxy bucket. That decision controls which response fields exist and which delivery features are available. Repost rejects any attempt to switch an existing bucket between modes. Create a new bucket and update the provider's webhook URL when the response contract needs to change.
Returns a static acknowledgement immediately after the provider request is received, then delivers to forwarders asynchronously. The provider does not wait for your application.
Holds the provider connection open, waits for the single downstream forwarder to respond, and returns that response directly to the provider.
When to use each mode#
- The webhook provider only requires an acknowledgement that the event was received.
- You need to deliver to more than one destination. Queue mode supports multiple forwarders on the same bucket.
- You need reliability features: retries with backoff, replay, failed-delivery recovery, functions, secrets, or rate limiting.
- Your application processing time would exceed the provider's HTTP timeout.
Queue mode: configuring the static acknowledgement#
Queue buckets respond to the provider before any forwarder receives the event. You control every part of that static response.
Status codebodyintegerrequiredThe HTTP status Repost returns to the sender. Must be an integer from 100 to 599. Defaults to 200.
Body formatbodystringSet to json or text. When set to json, a non-empty body must parse as valid JSON. Set to text for plain strings or provider-specific formats.
BodybodystringThe exact response body Repost returns with every acknowledgement. Optional. The dashboard pre-fills {"status":"received"}. Replace it with any string or valid JSON object that satisfies your provider.
{
"received": true,
"source": "repost"
}Most providers, including Stripe, GitHub, and Clerk, accept any 2xx response as a successful acknowledgement. Check your provider's documentation before changing the default status code.
Queue mode: fan-out to multiple forwarders#
One of the key advantages of Queue mode is that a single bucket can deliver the same event to many destinations in parallel. You add forwarders independently and each one gets its own retry, rate-limit, and failure configuration.
A single provider-facing URL captures every event from that stream.
Each forwarder delivers independently to its own destination: production, staging, data pipelines, or local dev.
Retries, backoff, rate limits, and failure handling are configured per forwarder, not per bucket.
Proxy mode: configuring the synchronous timeout#
Proxy buckets expose only the timeout because the downstream forwarder owns the response body, headers, and status code. Repost acts as a transparent pass-through.
TimeoutbodyintegerrequiredA positive integer in milliseconds. Controls how long Repost holds the provider connection open while waiting for the downstream forwarder. Defaults to 30000 ms. If the forwarder does not respond within this window, Repost returns a gateway error to the provider.
Set the Repost proxy timeout lower than the provider's own webhook timeout. When the provider retries requests it considers timed out, a shorter Repost timeout ensures it receives a clear gateway error rather than a stalled connection.
The downstream forwarder's response is returned verbatim to the provider: status, headers, and body.
Proxy mode supports exactly one forwarder per bucket. You cannot fan out in proxy mode.
Runtime retries, rate limits, functions, secrets, and failed-delivery recovery are not available for proxy forwarders.
Validation: why a save might be rejected#
Invalid status code
The queue acknowledgement status must be an integer from 100 to 599. Values outside that range are rejected.
Invalid JSON body
When body format is set to JSON, a non-empty body must parse as valid JSON. Malformed JSON is rejected on save.
Invalid proxy timeout
The proxy timeout must be a positive integer in milliseconds. Zero, negative values, and non-numeric input are rejected.
Changing modes: create a new bucket#
If you need to move a bucket from Queue to Proxy mode, or the reverse, you cannot do it in place. The migration path is straightforward:
Go through the creation flow and choose the mode you need. Configure the response contract for the new mode.
Set up the destination that should receive events from the new bucket.
In your provider's settings (Stripe, GitHub, Clerk, etc.), replace the old bucket domain with the new one.
Confirm events are arriving and being forwarded correctly before decommissioning the old bucket.