---
title: "Welcome"
description: "Learn the concepts behind how Repost receives webhooks: buckets, forwarders, and bucket modes."
---

<div className="w-full">
  <Section>
    <div className="max-w-4xl">
      <p className="text-lg leading-8 text-muted-foreground">Repost sits between webhook senders and your application. Providers send events to a bucket, Repost records the request, and forwarders deliver it to the services that should act on it.</p>
      <div className="mt-7 repost-action-row">
        <a href="#core-concepts" className="repost-action-primary">
          Explore concepts
          <Icon icon="arrow-right" size={15} />
        </a>
        <a href="#bucket-modes" className="repost-action-secondary">
          Compare modes
        </a>
      </div>
    </div>

    <div className="mt-10">
      <FlowDiagram
        sources={[
          { label: "Stripe", swatch: "#635BFF" },
          { label: "GitHub" },
          { label: "Clerk", swatch: "#6C47FF" },
        ]}
        destinations={[{ label: "API" }, { label: "Worker" }, { label: "Local" }]}
        hub={{ title: "Bucket", subtitle: "one ingress URL" }}
      />
    </div>
  </Section>

  <Section>
    <div id="core-concepts" />
    <SectionTitle title="Core concepts">
      Repost is built around a few ideas: where events enter, where they go, and how the bucket responds, then how you inspect, search, replay, and recover the traffic that flows through.
    </SectionTitle>

    <div className="not-typeset grid gap-5 md:grid-cols-2">
      <ConceptCard
        href="/docs/buckets/create"
        title="Bucket"
        diagram={
          <FlowDiagram
            frame={false}
            sources={[
              { label: "Stripe", swatch: "#635BFF" },
              { label: "GitHub" },
              { label: "Clerk", swatch: "#6C47FF" },
            ]}
            hub={{ title: "Bucket" }}
          />
        }
      >
        The public ingress point for webhook traffic.
      </ConceptCard>

      <ConceptCard
        href="/docs/forwarders/create"
        title="Forwarder"
        diagram={
          <FlowDiagram
            frame={false}
            destinations={[{ label: "API" }, { label: "Worker" }, { label: "Local" }]}
            hub={{ title: "Bucket" }}
          />
        }
      >
        A destination attached to a bucket.
      </ConceptCard>

      <ConceptCard
        href="/docs/buckets/response-behavior"
        title="Bucket modes"
        diagram={<ModeDiagram mode="queued" frame={false} />}
      >
        Queue or proxy the request response path.
      </ConceptCard>

      <ConceptCard
        href="/docs/history"
        title="Event history"
        diagram={<EventLog frame={false} />}
      >
        A record of requests and delivery outcomes.
      </ConceptCard>
    </div>

    <div className="not-typeset mt-5 grid gap-5 md:grid-cols-3">
      <ConceptCard
        href="/docs/history/search"
        title="Search"
        diagram={<SearchQuery frame={false} />}
      >
        Filter history with a powerful field, range, and JSON-path query language.
      </ConceptCard>

      <ConceptCard
        href="/docs/history/replay"
        title="Replay"
        diagram={<ReplayFlow frame={false} />}
      >
        Redeliver selected, filtered, or failed events through a forwarder.
      </ConceptCard>

      <ConceptCard
        href="/docs/history/failed-deliveries"
        title="Dead-letter queue"
        diagram={<DeadLetterQueue frame={false} />}
      >
        Exhausted deliveries park here to replay or archive.
      </ConceptCard>
    </div>
  </Section>

  <Section>
    <div id="buckets" />
    <SectionTitle title="Buckets">
      A bucket is the address you give to a webhook provider. It owns the event history, forwarding rules, and response behavior for that stream of traffic.
    </SectionTitle>

    <Columns cols={3} className="gap-y-4">
      <Card title="Stable source URL" icon="link">
        Use one Repost endpoint instead of wiring every provider directly to your application.
      </Card>

      <Card title="Clear boundary" icon="box">
        Split buckets by provider, environment, product area, or any other operational boundary.
      </Card>

      <Card title="Controlled behavior" icon="sliders-horizontal">
        Choose a bucket mode before sending traffic so the provider gets the right response.
      </Card>
    </Columns>
  </Section>

  <Section>
    <div id="forwarders" />
    <SectionTitle title="Forwarders">
      A forwarder connects a bucket to a destination. A destination can be your production API, a worker, an internal service, or a local development session.
    </SectionTitle>

    <Steps>
      <Step title="Receive">
        A provider sends the webhook to the bucket URL.
      </Step>
      <Step title="Record">
        Repost stores the inbound request with the bucket event history.
      </Step>
      <Step title="Deliver">
        Each active forwarder sends the event to its destination.
      </Step>
      <Step title="Inspect">
        The event page shows the request, forwarders, and responses in one place.
      </Step>
    </Steps>

    <div className="mt-10">
      <FlowDiagram
        caption="One bucket, many forwarders"
        sources={[{ label: "Provider", swatch: "#C146FF" }]}
        destinations={[{ label: "Production API" }, { label: "Background worker" }, { label: "Local dev" }]}
        hub={{ title: "Bucket", subtitle: "fan-out" }}
      />
    </div>
  </Section>

  <Section>
    <div id="bucket-modes" />
    <SectionTitle title="Bucket modes">
      Bucket mode decides what the webhook sender receives after it calls Repost.
    </SectionTitle>

    <Tabs>
      <Tab title="Queue mode" icon="clock">
        <ModePanel
          title="Acknowledge first, deliver after"
          subtitle="The default. The sender gets an immediate acknowledgement, then Repost delivers to your destinations asynchronously, with retries, backoff, and a dead-letter queue, so nothing is lost when an endpoint is down."
          diagram={<ModeDiagram mode="queued" frame={false} />}
        >
          <ModePoint icon="check" title="Immediate acknowledgement">
            Repost answers the provider right away, then delivers in the background.
          </ModePoint>
          <ModePoint icon="route" title="Fan out to many forwarders">
            Send the same event to your API, a worker, analytics, or local development.
          </ModePoint>
          <ModePoint icon="shield-check" title="Reliable and recoverable">
            Retries with backoff, a dead-letter queue and replay, functions, secrets, and rate limiting.
          </ModePoint>
        </ModePanel>
      </Tab>

      <Tab title="Proxy mode" icon="repeat">
        <ModePanel
          title="Return the destination response"
          subtitle="Repost is a transparent pipe: it forwards the request to a single destination and returns that destination's real response to the sender. One forwarder, one attempt, in real time."
          diagram={<ModeDiagram mode="proxy" frame={false} />}
        >
          <ModePoint icon="corner-down-left" title="Synchronous pass-through">
            The sender receives your application's actual status code and body.
          </ModePoint>
          <ModePoint icon="git-commit-horizontal" title="One forwarder, one attempt">
            No asynchronous retries or dead-letter recovery; the bucket has a single destination.
          </ModePoint>
          <ModePoint icon="search" title="Still recorded">
            The original request and downstream response are saved in event history.
          </ModePoint>
        </ModePanel>
      </Tab>
    </Tabs>

    <div className="mt-8 mb-3">
      <span className="repost-eyebrow">Feature comparison</span>
    </div>
    <div className="not-typeset overflow-x-auto rounded-xl border">
      <table className="w-full border-collapse text-sm">
        <thead>
          <tr className="bg-muted/50">
            <th className="px-4 py-3 text-left font-semibold text-foreground">Capability</th>
            <th className="w-36 px-4 py-3 text-center font-semibold text-foreground">Queued</th>
            <th className="w-36 px-4 py-3 text-center font-semibold text-foreground">Proxy</th>
          </tr>
        </thead>
        <tbody>
          <CompareRow title="Sender response" queued="Immediate ACK" proxy="Destination response" />
          <CompareRow title="Forwarders per bucket" queued="Many" proxy="One" />
          <CompareRow title="Delivery" queued="Asynchronous" proxy="Single attempt" />
          <CompareRow title="Retries and backoff" queued={true} proxy={false} />
          <CompareRow title="Dead-letter queue" queued={true} proxy={false} />
          <CompareRow title="Replay" queued={true} proxy={true} />
          <CompareRow title="Functions (transformations)" queued={true} proxy={false} />
          <CompareRow title="Per-forwarder secrets" queued={true} proxy={false} />
          <CompareRow title="Rate limiting" queued={true} proxy={false} />
        </tbody>
      </table>
    </div>
  </Section>

  <Section>
    <div id="event-history" />
    <SectionTitle title="Event history">
      Every event a bucket receives is recorded with its delivery outcomes, so you can confirm what the provider sent, where it went, and what each destination returned.
    </SectionTitle>

    <Columns cols={2} className="gap-y-4">
      <Card title="Request context" icon="inbox">
        Method, headers, body, source, timestamp, and the bucket that received the event.
      </Card>

      <Card title="Delivery context" icon="send">
        Forwarders, destination responses, and whether an event should be sent again.
      </Card>
    </Columns>
  </Section>

  <Section>
    <SectionTitle title="Start building">
      Set up your first end-to-end flow, from a bucket to your destination.
    </SectionTitle>

    <Columns cols={3} className="gap-y-4">
      <Card title="Create a bucket" icon="plus" href="/docs/buckets/create" cta="Start here" arrow="true">
        Define where webhook traffic enters Repost.
      </Card>

      <Card title="Choose a bucket mode" icon="toggle-right" href="/docs/buckets/response-behavior" cta="Compare modes" arrow="true">
        Queue an acknowledgement, or proxy the destination's response.
      </Card>

      <Card title="Add a forwarder" icon="route" href="/docs/forwarders/create" cta="Connect destinations" arrow="true">
        Route events to your production API, a worker, or an internal service.
      </Card>

      <Card title="Forward to localhost" icon="terminal" href="/docs/cli/local-forwarding" cta="Local dev" arrow="true">
        Receive live webhook traffic on your machine with the Repost CLI.
      </Card>

      <Card title="Inspect events" icon="search" href="/docs/history" cta="Debug traffic" arrow="true">
        Follow a request from sender to destination in event history.
      </Card>

      <Card title="Replay and recover" icon="rotate-ccw" href="/docs/history/replay" cta="Redeliver" arrow="true">
        Redeliver failed or filtered events through a forwarder.
      </Card>
    </Columns>
  </Section>
</div>
