Aller au contenu
KelkiDéveloppeurs

Guide des webhooks

À chaque changement de statut d'une de vos demandes, Kelki envoie un événement signé à votre adresse HTTPS. Aucune coordonnée, ni de la personne en clair, ni d'un professionnel.

Déclarer une adresse

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://conciergerie.example.com/kelki/webhook","events":["request.status_changed"]}'

L'événement

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 est la demande publique, telle que GET /requests/{request_id} la renvoie : coordonnées masquées, jamais de professionnel, jamais de provenance. Un événement ping sert aux essais.

Vérifier la signature

  1. Lisez Kelki-Signature : t=<horodatage unix>,v1=<HMAC-SHA256 hexadécimal>.
  2. Calculez HMAC-SHA256 de "<t>.<corps brut>" avec votre secret whsec_….
  3. Comparez à durée constante à chaque v1= de l'en-tête.
  4. Refusez un t de plus de 5 minutes (rejeu).

Code complet en JavaScript et en Python : exemples.

Répondre et dédoublonner

Ordre des événements

L'ordre d'arrivée n'est pas garanti. Fiez-vous à status_changed_at, et relisez la demande (GET /requests/{request_id}) ou son historique (GET /requests/{request_id}/events) en cas de doute.

Essayer et entretenir