Skip to content
KelkiDevelopers

Webhooks guide

On every status change of one of your requests, Kelki sends a signed event to your HTTPS endpoint. No contact details, neither the person's in clear nor a professional's.

Declaring an endpoint

curl -s https://kelki.ai/api/v1/webhook-endpoints \
  -H "Authorization: Bearer $KELKI_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: webhook-1" \
  -d '{"url":"https://concierge.example.com/kelki/webhook","events":["request.status_changed"]}'

The event

POST /kelki/webhook HTTP/1.1
Content-Type: application/json
Kelki-Signature: t=1762854000,v1=5f2b…
Kelki-Event-Id: evt_01JC0000000000000000000003

{"id": "evt_01JC0000000000000000000003", "type": "request.status_changed", "api_version": "1",
 "mode": "live", "created_at": "2026-11-11T10:15:41Z",
 "data": {"request": {"id": "req_01JC00000000000000000000RQ", "status": "sold",
                      "status_changed_at": "2026-11-11T10:15:40Z", "reference": "resa-2026-0042", "…": "…"}}}

data.request is the public request, as returned by GET /requests/{request_id}: masked contact details, never a professional, never the origin. A ping event is used for tests.

Verifying the signature

  1. Read Kelki-Signature: t=<unix timestamp>,v1=<hexadecimal HMAC-SHA256>.
  2. Compute HMAC-SHA256 of "<t>.<raw body>" with your whsec_… secret.
  3. Compare in constant time with each v1= of the header.
  4. Refuse a t older than 5 minutes (replay).

Full code in JavaScript and Python: examples.

Responding and deduplicating

Event order

Arrival order is not guaranteed. Rely on status_changed_at, and re-read the request (GET /requests/{request_id}) or its history (GET /requests/{request_id}/events) when in doubt.

Testing and maintenance