Skip to main content
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.

Queue mode

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.

Proxy mode

Repost holds the provider connection open, waits for a single downstream forwarder, and returns that destination’s response directly to the sender.
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.

​
Match the mode to your sender’s needs

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

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

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

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.

​
Create the bucket

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

Open the create flow

In the dashboard, click Create bucket. The first screen asks you to select the bucket type.
2

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

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

Pick a color

Color is a dashboard label only. It helps you distinguish buckets in the navigation sidebar and does not affect runtime behavior.
5

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

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.

​
Creation fields

These are the values Repost stores when the bucket is created.
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.
Required hex color. Used for dashboard organization only — it does not affect how events are ingested or delivered.
Either QUEUE or PROXY. This setting is permanent after creation and cannot be changed.
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.
Optional response body returned with the acknowledgement. The dashboard pre-fills {"status":"received"}. You can replace this with any string or valid JSON.
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.

​
What can block creation

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.
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.
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.
The proxy timeout must be a positive integer in milliseconds. Negative values, zero, and non-numeric input are rejected.
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.

Good boundaries

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.

Avoid mixing providers or environments

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.

​
After creation

Add an external forwarder

Send events to a public HTTP endpoint such as your production or staging server.

Add an internal forwarder

Hold events for a local CLI session during development or replay checks.

Review bucket settings

Tune status, response behavior, the generated endpoint label, and deletion guardrails after creation.
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.