Concepts
Webhooks
Signed HTTP callbacks when something happens in the buddy's world — HMAC-signed, 3 retries, 5-minute replay window.
Point Hatched at one of your endpoints and it will POST JSON whenever a
subscribed event fires — coin earned, badge awarded, streak milestone,
buddy evolved, etc. The signature is HMAC-SHA256 over ${timestamp}.${body}
using the secret we show once at creation.
Why webhooks
Widgets cover the presentation layer; webhooks cover the business layer. Unlock a course when a badge fires, notify Slack on streak milestones, sync coins into your own ledger.
Example
Subscribe to
badge.awarded. When "7 Day Streak" fires, your backend grants the user a premium feature for 24h.
How to set it up
- Add an endpoint under Settings → Webhooks and pick event types.
- Store the secret — it is shown only at creation time. Rotating the secret requires re-subscribing.
- On receipt, verify HMAC + timestamp, reject replays older than 5 minutes.
- Return 2xx quickly; non-2xx triggers retries at +5s, +30s, +5min.
See Handle webhooks for a complete verification example in Node.
Gotchas
- Sign over the raw body bytes, not a re-serialized JSON. JSON parsers reorder keys, which breaks the signature.
- Delivery log keeps every attempt — use it when something looks off.
- Webhooks are not ordered. If you need strict ordering, write to a queue on your side and sequence from there.