Webhooks

Register an HTTPS endpoint and we’ll POST every lifecycle event to it — signed, timestamped, and retried until you acknowledge it.

1. Register an endpoint

register
$ curl https://api.calder.click/v1/webhooks
  -d '{"url":"https://acme.com/hooks/calder",…}'

You’ll get a signing secret. Store it — it’s shown once.

2. Verify signatures

Every delivery includes a signature header computed as HMAC-SHA256(secret, raw_body). Compare with timingSafeEqual, never ===. Reject anything that doesn’t verify — shape alone is never trust.

3. Handle idempotently

We retry failed deliveries with backoff, so your handler will sometimes see the same event twice. Dedupe on the event ID, return 200 fast, and do slow work (emails, database writes) after acknowledging.

4. Inspect and replay

Every attempt is logged with status code, latency, and error. After an outage on your side, replay missed deliveries from the dashboard instead of asking us what happened.

Respond quickly. Acknowledge within a few seconds. If your handler needs a minute, accept first and process asynchronously — same philosophy as our API.