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

# Bucket Response Behavior: Queue Mode vs Proxy Mode

> Learn how Queue and Proxy bucket modes respond to webhook senders, which delivery features each mode supports, and how to tune response fields.

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.

<CardGroup cols={2}>
  <Card title="Queue bucket" icon="clock">
    Returns a static acknowledgement immediately after the provider request is received, then delivers to forwarders asynchronously. The provider does not wait for your application.
  </Card>

  <Card title="Proxy bucket" icon="zap">
    Holds the provider connection open, waits for the single downstream forwarder to respond, and returns that response directly to the provider.
  </Card>
</CardGroup>

## When to use each mode

<Tabs>
  <Tab title="Use Queue mode when…">
    * 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.
  </Tab>

  <Tab title="Use Proxy mode when…">
    * The webhook provider requires a meaningful response from your application at request time — for example, a challenge response or a dynamic acknowledgement.
    * You need the provider to see your application's actual HTTP status, headers, or body.
    * You are comfortable with the constraint of exactly one forwarder and no async delivery features.
  </Tab>
</Tabs>

## 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.

<ParamField body="Status code" type="integer" required>
  The HTTP status Repost returns to the sender. Must be an integer from `100` to `599`. Defaults to `200`.
</ParamField>

<ParamField body="Body format" type="string">
  Set 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.
</ParamField>

<ParamField body="Body" type="string">
  The 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.
</ParamField>

```json Example queue acknowledgement body theme={"languages":{"custom":["/languages/repost.json"]}}
{
  "received": true,
  "source": "repost"
}
```

<Tip>
  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.
</Tip>

## 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.

<CardGroup cols={3}>
  <Card title="One bucket" icon="inbox">
    A single provider-facing URL captures every event from that stream.
  </Card>

  <Card title="Many forwarders" icon="git-fork">
    Each forwarder delivers independently to its own destination — production, staging, data pipelines, or local dev.
  </Card>

  <Card title="Independent reliability" icon="shield-check">
    Retries, backoff, rate limits, and failure handling are configured per forwarder, not per bucket.
  </Card>
</CardGroup>

## 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.

<ParamField body="Timeout" type="integer" required>
  A 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.
</ParamField>

<Tip>
  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.
</Tip>

<CardGroup cols={3}>
  <Card title="One response owner" icon="reply">
    The downstream forwarder's response — status, headers, and body — is returned verbatim to the provider.
  </Card>

  <Card title="Exactly one forwarder" icon="arrow-right">
    Proxy mode supports exactly one forwarder per bucket. You cannot fan out in proxy mode.
  </Card>

  <Card title="No async recovery" icon="circle-off">
    Runtime retries, rate limits, functions, secrets, and failed-delivery recovery are not available for proxy forwarders.
  </Card>
</CardGroup>

## Validation: why a save might be rejected

<AccordionGroup>
  <Accordion title="Invalid status code" icon="hash">
    The queue acknowledgement status must be an integer from `100` to `599`. Values outside that range are rejected.
  </Accordion>

  <Accordion title="Invalid JSON body" icon="braces">
    When body format is set to JSON, a non-empty body must parse as valid JSON. Malformed JSON is rejected on save.
  </Accordion>

  <Accordion title="Invalid proxy timeout" icon="timer-off">
    The proxy timeout must be a positive integer in milliseconds. Zero, negative values, and non-numeric input are rejected.
  </Accordion>
</AccordionGroup>

## 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:

<Steps>
  <Step title="Create a new bucket with the correct mode">
    Go through the creation flow and choose the mode you need. Configure the response contract for the new mode.
  </Step>

  <Step title="Add a forwarder to the new bucket">
    Set up the destination that should receive events from the new bucket.
  </Step>

  <Step title="Update the provider's webhook URL">
    In your provider's settings (Stripe, GitHub, Clerk, etc.), replace the old bucket domain with the new one.
  </Step>

  <Step title="Verify delivery on the new bucket">
    Confirm events are arriving and being forwarded correctly before decommissioning the old bucket.
  </Step>
</Steps>

## Related pages

<CardGroup cols={3}>
  <Card title="Bucket domains" icon="globe" href="/docs/buckets/domains">
    Change the generated Repost endpoint label and understand how paths are preserved.
  </Card>

  <Card title="Bucket settings" icon="settings" href="/docs/buckets/settings">
    Edit identity, status, response behavior, domains, and deletion guardrails.
  </Card>

  <Card title="Forwarder configuration" icon="route" href="/docs/forwarders/configuration">
    Tune destination delivery behavior after the bucket accepts the webhook.
  </Card>
</CardGroup>