Operating modes

Every endpoint runs in one of three operating modes. The mode controls how much of each request catchbin stores and whether it fans events out to a connected CLI. Mode is set per endpoint and can be changed later.

store_and_forward default

The default for a new endpoint, and the mode you use for local development.

catchbin stores the full request and pushes each captured event to any connected catchbin forward session. This is the mode that lets you develop against real provider webhooks without a tunnel: the provider talks to the permanent catchbin URL, and the CLI relays events to your localhost.

Caution

Do not leave a production endpoint on store_and_forward. This mode fans every captured webhook out to any connected CLI session. On an endpoint that receives production traffic, that is an data-exposure surprise. Use store_only for a production parallel receiver.

store_only

catchbin stores the full request but does not fan out to any CLI. Use this for the production parallel receiver pattern below — you want a durable, inspectable record of production webhooks without relaying live production data to a developer’s machine.

metadata_only

catchbin reads the body into memory to verify the signature and extract the event type, then discards it. Only headers, timestamps, the remote IP, and the verification result are persisted — the body is never written to disk, database, or logs.

Use this when the payloads contain data you do not want stored at all. Events captured in this mode cannot be replayed, because there is no stored body to send.

The production parallel-receiver pattern

Most providers let you configure more than one webhook URL. That means you can add catchbin as a second endpoint alongside your real production backend. Both receive every event independently and at the same time:

Provider (Stripe, etc.)
    ├──▶ your production backend   (primary, unchanged)
    └──▶ catchbin URL             (parallel capture for inspection)

There is no proxy and no sequential forwarding, so catchbin adds zero latency to production and cannot cause a production failure. Its role is purely observational: inspect, search, and replay what production actually received. Run this endpoint in store_only or metadata_only.

Note

This pattern works for Stripe and for GitHub repository and organization webhooks, which allow multiple independently-configured endpoints. It does not work for a GitHub App, which has exactly one webhook URL — adopting the pattern there requires fanning out inside your own backend. See the GitHub provider guide.

What catchbin is not

catchbin does not sit permanently in front of your production backend, own retry logic, or provide delivery guarantees. That is a different product. catchbin captures, stores, inspects, and replays — nothing in the request path of your production traffic.