Docs

Five minutes to your first signed, retried, logged webhook.

Send your first event

KEY=<your HOOKWELL_API_KEY>

# 1. Register an endpoint
curl -s -H "X-API-Key: $KEY" localhost:8000/v1/endpoints \
  -d '{"url":"https://acme.com/hooks","secret":"whsec_...","event_types":["billing.*"]}'

# 2. Send an event
curl -s -H "X-API-Key: $KEY" localhost:8000/v1/events \
  -d '{"type":"billing.subscription.created","payload":{"customer":"cus_1"}}'
# {"event_id":"evt_...","deliveries":["dlv_..."]}
# -> signed, fanned out, retried with backoff, logged. That's the whole API.

Receive webhooks (inbound gateway)

# 1. Register a source
curl -s -H "X-API-Key: $KEY" localhost:8000/v1/inbound-sources \
  -d '{"name":"stripe","mode":"stripe","secret":"whsec_stripe","event_prefix":"billing"}'
# {"id":"src_..."}

# 2. Point Stripe at: POST /v1/inbound/src_...
# Inbound events are signature-verified, normalized to
# billing.stripe.<event>, and fanned out to endpoints.

Inspect, replay, DLQ

# delivery + full attempt history
curl -s -H "X-API-Key: $KEY" localhost:8000/v1/deliveries/dlv_...

# dead-letter queue
curl -s -H "X-API-Key: $KEY" localhost:8000/v1/dlq

# replay a delivery from a clean slate
curl -s -X POST -H "X-API-Key: $KEY" \
  localhost:8000/v1/deliveries/dlv_.../replay

White-label customer portal API

# mint a scoped token (raw token shown ONCE)
curl -s -H "X-API-Key: $KEY" localhost:8000/v1/portal/tokens \
  -d '{"customer_id":"acme","endpoint_ids":["ep_..."],"label":"Acme portal"}'

# customers use X-Portal-Token to see only their deliveries
curl -s -H "X-Portal-Token: <token>" localhost:8000/v1/portal/deliveries

Verify a delivery (receiver side)

# Every outbound POST carries Standard Webhooks headers:
#   webhook-id:        dlv_...   (dedupe key — store it, ignore repeats)
#   webhook-timestamp: <unix seconds>
#   webhook-signature: v1,<base64 HMAC-SHA256 of "id.timestamp.body">
# Verify with any Standard Webhooks library — endpoint secrets are
# issued in whsec_ + base64 format, exactly as those libraries expect.
# Legacy: x-hookwell-signature-hex carries the same digest hex-encoded
# for receivers still on the pre-2026-10 format.