Skip to content
catchook
Documentation

Concepts

Endpoints

One inbound URL, one provider, one verification method — plus pausing and secret rotation.

An endpoint is the URL you give to a provider. It owns three things: which provider is allowed to post to it, how requests are verified, and which destinations the events fan out to.

https://events.catchook.com/e/end_60e42bf9513149f2b89dddaa779079a4

The id is unguessable, but it is not a secret in the way an API key is — it travels in provider dashboards and configuration files. Verification, not obscurity, is what stops someone else posting to it.

Providers

The provider field is what makes an endpoint’s verification and response behaviour correct for the service posting to it. Verified against each provider’s documentation today: Stripe, GitHub, Shopify, Linear, and Twilio’s status callbacks.

Anything else can use a generic endpoint with an explicit verification method — it just means Catchook has no provider-specific handling for it.

Pausing

A paused endpoint returns 200 to the provider and queues nothing. That is deliberate: providers disable webhook subscriptions that keep failing, so answering 503 during a planned pause can cost you the subscription itself.

Events received while paused are not recorded and cannot be replayed afterwards. Pause is a stop, not a buffer.

Pausing takes up to 60 seconds to reach the receive path, so treat it as “shortly” rather than “immediately”.

Rotating the signing secret

Rotation sets a new provider secret on the endpoint. Because the provider signs with its own copy, the order matters:

  1. Generate the new secret in the provider’s dashboard.
  2. Set it on the endpoint.
  3. Confirm events are still verifying.

Between steps 1 and 2, requests signed with the new secret fail verification and are rejected with 401. Providers retry, so a short window is usually recovered automatically — but it is a window, and it is the reason to do this deliberately rather than during an incident.

Rate limiting on receive

Each endpoint accepts up to 12,000 requests per minute (~200/sec). This is an abuse guard against someone hammering a known endpoint id, not a cap meant to constrain real provider traffic.