Configure webhooks

Webhook setup is in the dashboard. Configure once; subscribe to the events you care about. The full event list is in the API webhooks reference.

Add an endpoint

Dashboard → Settings → Webhooks.

1. Add URL

   Public HTTPS URL. We won’t post to plain HTTP.

2. Pick events

   All-or-individual. Start narrow.

3. Copy the signing secret

   Shown once. Used to verify each request — see API webhooks.

4. Send a test

   The dashboard’s Send test event button posts a synthetic domain.registered with id: evt_test_.... Useful for verifying your handler before any real event lands.

What to do in your handler

• Verify the signature first. Reject unsigned requests.
• Read the event id and check for duplicates — we may retry, and a network blip can cause re-delivery after you 200’d. Build idempotency on event.id.
• Enqueue the work and return 200 quickly. Long handlers cause timeouts and retries.

Local development

ngrok or a Cloudflare quick tunnel works. The dashboard accepts any public HTTPS URL.

ngrok http 8787
# Set webhook URL to the ngrok https URL

The dashboard shows recent deliveries with response codes. Bad endpoints get exponential backoff (30s → 24h) and pause after 24h of failures.

Replay

Need to re-deliver a missed event? In the dashboard, open the event detail and click Replay. The endpoint receives the original payload with the same id — your idempotency layer should treat it as a no-op or proceed depending on intent.

Internal webhooks

The endpoints under /api/v1/webhooks/stripe and /api/v1/webhooks/clerk are inbound — Stripe and Clerk POST to us. They are not user-configurable.