A bucket is the ingress point for a stream of inbound webhooks. 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.
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.
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.
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.
Queue mode supports multiple forwarders on the same bucket, retries with backoff, replay, failed-delivery handling, functions, secrets, and rate limiting.
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.
In the dashboard, click Create bucket. The first screen asks you to select the bucket type.
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.
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.
Color is a dashboard label only. It helps you distinguish buckets in the navigation sidebar and does not affect runtime behavior.
Queue buckets display status code and body fields. Proxy buckets display the timeout field. You can adjust these values later from bucket settings.
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.
Name
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.
Color
Required hex color. Used for dashboard organization only: it does not affect how events are received or delivered.
Mode
Either QUEUE or PROXY. This setting is permanent after creation and cannot be changed.
Queue status
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.
Queue body
Optional response body returned with the acknowledgement. The dashboard pre-fills {"status":"received"}. You can replace this with any string or valid JSON.
Proxy timeout
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#
The name is already taken
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.
Plan bucket limit reached
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.
Invalid queue acknowledgement
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.
Invalid proxy timeout
The proxy timeout must be a positive integer in milliseconds. Negative values, zero, and non-numeric input are rejected.
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.
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.
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#
Send events to a public HTTP endpoint such as your production or staging server.
Hold events for a local CLI session during development or replay checks.
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.