Quickstart

This walks through the API. Everything here is also doable from the dashboard.

1. Get an API key#

API keys are scoped to a project, and every organization gets a default project when it is created. Keys look like ck_… and are shown once, at creation.

export CATCHOOK_API_KEY=ck_live_...

Every request below authenticates with it:

curl https://api.catchook.com/projects \
  -H "Authorization: Bearer $CATCHOOK_API_KEY"

Your organization is never passed explicitly — it is resolved from the key.

2. Create an endpoint#

An endpoint is the URL the provider will post to. It needs the provider and how incoming requests should be verified:

curl -X POST https://api.catchook.com/endpoints \
  -H "Authorization: Bearer $CATCHOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Stripe production",
    "provider": "stripe",
    "verification_method": "hmac_sha256"
  }'

The response carries the id and the receiving URL:

{
  "data": {
    "id": "end_60e42bf9513149f2b89dddaa779079a4",
    "name": "Stripe production",
    "provider": "stripe",
    "verification_method": "hmac_sha256",
    "url": "https://events.catchook.com/e/end_60e42bf9513149f2b89dddaa779079a4",
    "paused": false
  },
  "timestamp": "2026-08-29T10:04:11.284Z"
}

3. Give it the provider’s signing secret#

Catchook verifies the provider’s signature before doing anything else, so it needs the same secret the provider signs with — whsec_… in Stripe’s case. Set it on the endpoint, then paste the endpoint URL into the provider’s webhook settings.

See Signature verification for what each method expects.

4. Add a destination#

Nothing is delivered anywhere until an endpoint has at least one destination:

curl -X POST https://api.catchook.com/endpoints/end_60e4.../destinations \
  -H "Authorization: Bearer $CATCHOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API",
    "receiver_url": "https://api.example.com/webhooks/stripe",
    "retry_max_attempts": 5
  }'

The response includes a catchook_secret. Catchook signs every delivery to this destination with it, so your handler can confirm the request came from Catchook and not from someone who guessed the URL — see Verifying deliveries.

5. Send a test event#

Trigger a real webhook from the provider’s dashboard. Within a second or so it is queryable:

curl "https://api.catchook.com/events?limit=5" \
  -H "Authorization: Bearer $CATCHOOK_API_KEY"

If nothing arrives, the usual causes, in order: the endpoint is paused, the signing secret does not match the provider’s, or the provider is still pointed at the old URL.

Next#

Run catchook listen to put those same webhooks on your laptop while you write the handler.