# 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](https://kelki.ai/developers/fr/rate-limits/)). 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=,v1=`. - Calculez HMAC-SHA256 de `"."` avec votre secret `whsec_…`. - Comparez à durée constante à chaque `v1=` de l'en-tête. - Refusez un `t` de plus de 5 minutes (rejeu). Code complet en JavaScript et en Python : [exemples](https://kelki.ai/developers/fr/examples/#webhooks). ## Répondre et dédoublonner - Répondez `2xx` en 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 `410` dé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}/test` envoie un `ping`. - En bac à sable, `POST /sandbox/requests/{request_id}/simulate` déclenche les vrais événements ([bac à sable](https://kelki.ai/developers/fr/sandbox/)). - `POST /webhook-endpoints/{endpoint_id}/rotate-secret` remplace le secret : pendant 24 heures, chaque événement porte deux signatures (ancien et nouveau secret). ## Sur cette page - URL : https://kelki.ai/developers/fr/webhooks/ - Langue : fr - fr : https://kelki.ai/developers/fr/webhooks/ - en : https://kelki.ai/developers/en/webhooks/ - x-default : https://kelki.ai/developers/ - Portail : https://kelki.ai/developers/llms.txt