# 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](https://kelki.ai/developers/en/rate-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=,v1=`. - Compute HMAC-SHA256 of `"."` with your `whsec_…` secret. - Compare in constant time with each `v1=` of the header. - Refuse a `t` older than 5 minutes (replay). Full code in JavaScript and Python: [examples](https://kelki.ai/developers/en/examples/#webhooks). ## Responding and deduplicating - Reply `2xx` within 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 `410` response 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}/test` sends a `ping`. - In the sandbox, `POST /sandbox/requests/{request_id}/simulate` triggers the real events ([sandbox](https://kelki.ai/developers/en/sandbox/)). - `POST /webhook-endpoints/{endpoint_id}/rotate-secret` replaces the secret: for 24 hours, each event carries two signatures (old and new secret). ## About this page - URL : https://kelki.ai/developers/en/webhooks/ - Language : en - fr : https://kelki.ai/developers/fr/webhooks/ - en : https://kelki.ai/developers/en/webhooks/ - x-default : https://kelki.ai/developers/ - Portal : https://kelki.ai/developers/llms.txt