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

# Create a Repost Bucket for Webhook Ingestion Today

> Learn how to create a Repost bucket, choose between Queue and Proxy mode, and configure the response contract for your webhook providers.

A bucket is the ingress point for a stream of webhook events. Creating one defines the URL your providers call, the response contract they receive, and the forwarding model Repost uses for every event that arrives in that bucket.

## Choose the mode first

Response mode is the single most important decision you make at creation time. Mode-specific fields — like status code, body, or timeout — can be tuned later from settings, but **the mode itself is permanent**. A queued bucket can never become a proxy bucket, and vice versa. Make this choice before sending real provider traffic.

<CardGroup cols={2}>
  <Card title="Queue mode" icon="shield-check">
    The sender receives an immediate acknowledgement. Repost records the event and delivers it asynchronously to one or more forwarders, with retries, replay, and configurable status and body.
  </Card>

  <Card title="Proxy mode" icon="zap">
    Repost holds the provider connection open, waits for a single downstream forwarder, and returns that destination's response directly to the sender.
  </Card>
</CardGroup>

<Warning>
  Pick the mode before directing real provider traffic to the bucket. To change modes later, create a new bucket and update the provider's webhook URL to point to it.
</Warning>

## Match the mode to your sender's needs

Choose the mode that reflects what the webhook provider actually expects when it calls your endpoint.

<Tabs>
  <Tab title="Queue mode">
    <Steps>
      <Step title="Use when the sender only needs an acknowledgement">
        Queue mode replies immediately with a static HTTP status and body, then handles delivery after the provider request has completed. The provider does not wait for your application to process the event.
      </Step>

      <Step title="Use for multiple destinations and reliability controls">
        Queue mode supports multiple forwarders on the same bucket, retries with backoff, replay, failed-delivery handling, functions, secrets, and rate limiting.
      </Step>

      <Step title="Configure the ACK response">
        The default acknowledgement status is `200` and the default body is `{"status":"received"}`. You can set any status code between `100` and `599` and provide any string or valid JSON as the body.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Proxy mode">
    <Steps>
      <Step title="Use when the sender needs your destination's response">
        Proxy mode keeps the provider request open while the downstream forwarder processes the webhook. The response your application returns is passed back to the provider.
      </Step>

      <Step title="Expect exactly one forwarder">
        A proxy bucket supports exactly one forwarder. Retry configuration, rate limiting, functions, secrets, and failed-delivery recovery are not available for proxy forwarders.
      </Step>

      <Step title="Set the timeout">
        The default proxy timeout is `30000` ms. The value must be a positive integer. Set it below the provider's own timeout when the provider retries timed-out requests.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Create the bucket

From the Repost dashboard, bucket creation walks you through type selection, configuration, and an optional forwarder step.

<Steps>
  <Step title="Open the create flow">
    In the dashboard, click **Create bucket**. The first screen asks you to select the bucket type.
  </Step>

  <Step title="Choose Queue or Proxy">
    Queue is the default recommendation for reliable asynchronous delivery. Choose Proxy only when the webhook provider requires a response from your application at request time.
  </Step>

  <Step title="Name the bucket">
    Repost converts the name into a URL-safe slug and shows the generated domain as you type. The slug and endpoint must be globally unique — if the name is taken, choose a more specific one such as `stripe-production` or `stripe-staging`.
  </Step>

  <Step title="Pick a color">
    Color is a dashboard label only. It helps you distinguish buckets in the navigation sidebar and does not affect runtime behavior.
  </Step>

  <Step title="Configure the response contract">
    Queue buckets display status code and body fields. Proxy buckets display the timeout field. You can adjust these values later from bucket settings.
  </Step>

  <Step title="Continue to forwarders">
    After the bucket is created, you can add an external forwarder, add an internal forwarder, or skip and configure forwarders later. A queue bucket records events even before a forwarder exists. A proxy bucket needs a deliverable forwarder; without one, incoming requests receive a gateway error.
  </Step>
</Steps>

## Creation fields

These are the values Repost stores when the bucket is created.

<AccordionGroup>
  <Accordion title="Name" icon="tag">
    Required. Repost uses this to generate the bucket slug and the initial endpoint label. The name must produce a slug and domain that are not already in use.
  </Accordion>

  <Accordion title="Color" icon="palette">
    Required hex color. Used for dashboard organization only — it does not affect how events are ingested or delivered.
  </Accordion>

  <Accordion title="Mode" icon="toggle-left">
    Either `QUEUE` or `PROXY`. This setting is permanent after creation and cannot be changed.
  </Accordion>

  <Accordion title="Queue status" icon="hash">
    An integer from `100` to `599`. Defaults to `200`. This is the HTTP status code Repost returns to the webhook provider for every incoming event.
  </Accordion>

  <Accordion title="Queue body" icon="braces">
    Optional response body returned with the acknowledgement. The dashboard pre-fills `{"status":"received"}`. You can replace this with any string or valid JSON.
  </Accordion>

  <Accordion title="Proxy timeout" icon="timer">
    A positive integer in milliseconds. Defaults to `30000`. This is how long Repost waits for the downstream forwarder before returning a gateway error to the provider.
  </Accordion>
</AccordionGroup>

## What can block creation

<AccordionGroup>
  <Accordion title="The name is already taken" icon="ban">
    Bucket slugs and generated domains are globally unique. If the name produces a slug or domain already in use, choose a more specific name such as `stripe-production` or `stripe-staging`.
  </Accordion>

  <Accordion title="Plan bucket limit reached" icon="gauge">
    Bucket count is capped by your plan: **Free** allows 3, **Starter** allows 25, **Pro** allows 100, and **Enterprise** is unlimited. When you reach the limit, Repost prompts you to upgrade before creating another bucket.
  </Accordion>

  <Accordion title="Invalid queue acknowledgement" icon="circle-alert">
    The queue status code must be a valid integer from `100` to `599`. If you supply a response body in JSON format, it must parse as valid JSON.
  </Accordion>

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

## Recommended bucket boundaries

Buckets are easiest to operate when each one maps to a single provider and a single environment. Clear boundaries keep history, response behavior, and forwarding rules straightforward.

<CardGroup cols={2}>
  <Card title="Good boundaries" icon="check">
    Name buckets after their source and environment: `stripe-production`, `stripe-staging`, `clerk-events`. Create one bucket per product area when the same provider sends unrelated event streams.
  </Card>

  <Card title="Avoid mixing providers or environments" icon="split">
    Do not combine unrelated providers or environments into one bucket to reduce bucket count. Mixed buckets make history, response configuration, and forwarding rules harder to reason about.
  </Card>
</CardGroup>

## After creation

<CardGroup cols={3}>
  <Card title="Add an external forwarder" icon="globe" href="/docs/forwarders/create">
    Send events to a public HTTP endpoint such as your production or staging server.
  </Card>

  <Card title="Add an internal forwarder" icon="monitor" href="/docs/forwarders/create">
    Hold events for a local CLI session during development or replay checks.
  </Card>

  <Card title="Review bucket settings" icon="settings" href="/docs/buckets/settings">
    Tune status, response behavior, the generated endpoint label, and deletion guardrails after creation.
  </Card>
</CardGroup>

<Note>
  A queue bucket can record events before any forwarder is attached. A proxy bucket needs at least one deliverable forwarder configured — until then, provider requests receive a gateway error because there is no downstream response to return.
</Note>