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"]}'
- HTTPS seulement, nom de domaine public (pas d'adresse IP), certificat valide. Toutes les adresses résolues du nom doivent être publiques ; la connexion se fait vers l'adresse vérifiée.
- La réponse contient le secret de signature
whsec_…, montré une seule fois. - Une adresse appartient à un mode : les demandes de test vont aux adresses du mode test.
- Nombre d'adresses selon le plan : 2, 5 ou 10 (limites). Portée
webhooks.manage.
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
- Lisez
Kelki-Signature:t=<horodatage unix>,v1=<HMAC-SHA256 hexadécimal>. - Calculez HMAC-SHA256 de
"<t>.<corps brut>"avec votre secretwhsec_…. - Comparez à durée constante à chaque
v1=de l'en-tête. - Refusez un
tde plus de 5 minutes (rejeu).
Code complet en JavaScript et en Python : exemples.
Répondre et dédoublonner
- Répondez
2xxen moins de 5 secondes ; traitez ensuite en tâche de fond. Aucune redirection n'est suivie. - Sans
2xx: nouvel essai après 1 min, 5 min, 30 min, 2 h, 6 h, 12 h et 24 h. - Un même événement peut arriver deux fois : dédoublonnez sur
Kelki-Event-Id. - Une réponse
410désactive l'adresse ; 50 échecs de suite aussi (disabled_reason).
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
POST /webhook-endpoints/{endpoint_id}/testenvoie unping.- En bac à sable,
POST /sandbox/requests/{request_id}/simulatedéclenche les vrais événements (bac à sable). POST /webhook-endpoints/{endpoint_id}/rotate-secretremplace le secret : pendant 24 heures, chaque événement porte deux signatures (ancien et nouveau secret).