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

# Repost Bucket Domains, Endpoint Labels, and URL Routing

> Understand how Repost bucket domains work, how to change the endpoint label, and how the request path is preserved on incoming events.

A bucket domain is the Repost host your webhook provider calls. The host identifies which bucket receives the request, and the path after the host is preserved on every event Repost records. Understanding how domains and labels work helps you configure providers correctly and avoid routing gaps when you rename or reorganize buckets.

## How the domain is structured

The Repost dashboard splits each bucket endpoint into two parts: an editable label that you control, and a fixed base domain that Repost manages. The full endpoint your provider calls is the label joined to the base domain.

<CardGroup cols={2}>
  <Card title="Editable label" icon="pencil">
    The prefix you set and can change. For example, `stripe-prod`. This is what makes each bucket's URL unique and recognizable.
  </Card>

  <Card title="Fixed base domain" icon="lock">
    The Repost-managed suffix appended to your label. It never changes — you cannot edit or replace it with a custom domain today.
  </Card>
</CardGroup>

If your label is `stripe-prod`, the full bucket host displayed in the dashboard is `stripe-prod.<base-domain>`. If the provider also requires a specific path, append it after the host — for example, `https://stripe-prod.<base-domain>/webhooks/stripe`.

<Info>
  Custom domains are listed in the Domains settings page as an upcoming capability. Generated Repost domains are the configurable endpoint available today.
</Info>

## Bucket name vs. endpoint label

The bucket name and the endpoint label are separate fields that serve different purposes. Changing one does not automatically change the other.

<CardGroup cols={2}>
  <Card title="Bucket name" icon="tag">
    Used for dashboard identity — it appears in the sidebar, history, and settings. Renaming a bucket updates its internal slug but does **not** change the provider-facing endpoint URL.
  </Card>

  <Card title="Endpoint label" icon="globe">
    Used for incoming webhook routing. Changing the label changes the URL your provider must call. The bucket name is unaffected.
  </Card>
</CardGroup>

<Warning>
  The bucket domain is determined by the endpoint label, not the bucket name. Renaming your bucket in settings does **not** update the URL your provider is calling. Update the endpoint label under Domains if you need to change the provider-facing URL.
</Warning>

## How paths are preserved

When a provider calls your bucket URL with a path — for example, `https://stripe-prod.<base-domain>/webhooks/v2/events` — Repost preserves the full path on the recorded event.

<CardGroup cols={2}>
  <Card title="Transparent path pass-through" icon="arrow-right">
    The path your provider sends is attached to the event record and forwarded to destinations that use transparent mode. Your application receives the same path the provider sent.
  </Card>

  <Card title="Path ignored in locked mode" icon="lock">
    When a forwarder uses locked path mode, the destination URL path is fixed regardless of what the provider sent. The event still records the original path.
  </Card>
</CardGroup>

<Tip>
  If your provider supports configuring a webhook URL with a path, use a meaningful path such as `/webhooks/stripe` to make event history easier to filter and read.
</Tip>

## Change the endpoint label

You can change the endpoint label at any time from the bucket's Domains settings page. Repost validates the new label before saving.

<Steps>
  <Step title="Open the Domains settings page">
    Navigate to the bucket in the dashboard, go to **Settings**, and select the **Domains** section.
  </Step>

  <Step title="Enter a new label">
    Type the label you want to use. The dashboard lowercases letters and strips dots as you type. Other invalid characters place the form in an error state.
  </Step>

  <Step title="Wait for the availability check">
    Repost checks whether the full generated domain is available. The Save button stays disabled until the check passes. If the label is taken, try a more specific value.
  </Step>

  <Step title="Save and update your provider">
    After saving, the old URL stops accepting traffic immediately. Update the webhook URL in your provider's settings before the next event is sent.
  </Step>
</Steps>

<Warning>
  Changing the endpoint label takes effect immediately. There is no grace period — the old URL stops working as soon as you save. Update your provider's webhook configuration before making this change in production.
</Warning>

## Valid endpoint labels

Labels follow DNS-safe rules so the generated endpoint can be routed reliably.

<AccordionGroup>
  <Accordion title="Allowed characters" icon="letter-case">
    Lowercase letters (`a`–`z`), numbers (`0`–`9`), and hyphens (`-`). Uppercase letters and dots are not allowed — the dashboard lowercases and removes dots automatically as you type.
  </Accordion>

  <Accordion title="Length" icon="ruler">
    The label must be between `1` and `63` characters long.
  </Accordion>

  <Accordion title="Edge rules" icon="brackets">
    The label cannot start or end with a hyphen. For example, `-stripe` and `stripe-` are invalid; `stripe-prod` is valid.
  </Accordion>
</AccordionGroup>

```text Valid labels theme={"languages":{"custom":["/languages/repost.json"]}}
stripe-prod
github-events
webhook01
clerk-production
```

```text Invalid labels theme={"languages":{"custom":["/languages/repost.json"]}}
StripeProd        (uppercase letters)
stripe.prod       (contains a dot)
-stripe           (starts with a hyphen)
stripe-           (ends with a hyphen)
```

## Use the domain in your provider's webhook settings

When configuring the webhook URL in your provider's dashboard — Stripe, GitHub, Clerk, or any other service — copy the full generated domain from the Repost bucket Domains page. Use the complete URL including any path your integration requires.

<CardGroup cols={2}>
  <Card title="Host only" icon="server">
    Use `https://stripe-prod.<base-domain>` when the provider sends all event types to a single URL and your forwarder handles path routing.
  </Card>

  <Card title="Host with path" icon="link">
    Use `https://stripe-prod.<base-domain>/webhooks/stripe` when your application expects events at a specific path, or when you want to make event history easier to filter.
  </Card>
</CardGroup>

## Related pages

<CardGroup cols={3}>
  <Card title="Response behavior" icon="reply" href="/docs/buckets/response-behavior">
    Configure the acknowledgement or proxy timeout that providers receive when they call the bucket URL.
  </Card>

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

  <Card title="Event history" icon="history" href="/docs/history">
    Confirm provider calls are arriving at the correct bucket after an endpoint change.
  </Card>
</CardGroup>