Webhooks

HMAC-signed push delivery of events to your HTTPS endpoint.

Subscribe

curl -X POST https://klaw-voice.netlify.app/api/v1/webhooks \
  -H "Authorization: Bearer $KLAW_KEY" -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/klaw",
    "events": ["call.ended", "call.transcribed", "message.received"],
    "description": "CRM sync"
  }'

• url must be HTTPS and publicly reachable (private/internal addresses are rejected).
• events lists types from the table, or ["*"] for all.
• The response includes your signing secret whsec_... once — store it.

Manage with GET /api/v1/webhooks, GET|DELETE /api/v1/webhooks/{id}, POST /api/v1/webhooks/{id}/secret (re-reveal), and POST /api/v1/webhooks/{id}/ping (sends a webhook.ping you can verify end-to-end).

Verify deliveries

Each delivery carries:

Header	Meaning
X-Klaw-Signature	sha256= + HMAC-SHA256 of the raw body with your whsec_ secret
X-Klaw-Event	The event type
X-Klaw-Delivery	Unique delivery id

import crypto from 'node:crypto'

function verify(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
  return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected))
}

Respond 2xx quickly — deliveries time out after 4 seconds. Delivery status and the last attempt time are visible on the subscription record.