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"]}'
- HTTPS only, public domain name (no IP address), valid certificate. All addresses the name resolves to must be public; the connection is made to the verified address.
- The response contains the
whsec_…signing secret, shown only once. - An endpoint belongs to one mode: test requests go to test-mode endpoints.
- Number of endpoints by plan: 2, 5 or 10 (limits). Scope
webhooks.manage.
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
- Read
Kelki-Signature:t=<unix timestamp>,v1=<hexadecimal HMAC-SHA256>. - Compute HMAC-SHA256 of
"<t>.<raw body>"with yourwhsec_…secret. - Compare in constant time with each
v1=of the header. - Refuse a
tolder than 5 minutes (replay).
Full code in JavaScript and Python: examples.
Responding and deduplicating
- Reply
2xxwithin 5 seconds; process afterwards in the background. No redirect is followed. - Without
2xx: new attempt after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h and 24 h. - The same event may arrive twice: deduplicate on
Kelki-Event-Id. - A
410response disables the endpoint; so do 50 consecutive failures (disabled_reason).
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
POST /webhook-endpoints/{endpoint_id}/testsends aping.- In the sandbox,
POST /sandbox/requests/{request_id}/simulatetriggers the real events (sandbox). POST /webhook-endpoints/{endpoint_id}/rotate-secretreplaces the secret: for 24 hours, each event carries two signatures (old and new secret).