Webhooks (référence)
Abonnements aux changements de statut, signés en HMAC-SHA256.
Adresse de base : https://kelki.ai/api/v1.
GET /webhook-endpoints— Lister vos adresses de webhooksPOST /webhook-endpoints— Déclarer une adresse de webhookGET /webhook-endpoints/{endpoint_id}— Lire une adresse de webhookDELETE /webhook-endpoints/{endpoint_id}— Supprimer une adresse de webhookPOST /webhook-endpoints/{endpoint_id}/test— Envoyer un événement « ping »POST /webhook-endpoints/{endpoint_id}/rotate-secret— Remplacer le secret de signature
GET /webhook-endpoints
Lister vos adresses de webhooks
Authentification : clé API (Authorization: Bearer kk_…) ou jeton OAuth 2.0 (portée webhooks.manage).
Réponses
| Code | Description | Contenu |
|---|---|---|
200 | Adresses déclarées pour le mode courant. | application/json WebhookEndpointList |
401 | Identifiants absents, invalides, expirés ou révoqués. | application/problem+json Problem |
POST /webhook-endpoints
Déclarer une adresse de webhook
HTTPS seulement, nom de domaine public (pas d'adresse IP), certificat valide. Le secret est montré une seule fois.
Authentification : clé API (Authorization: Bearer kk_…) ou jeton OAuth 2.0 (portée webhooks.manage).
Paramètres
| Nom | Où | Requis | Type | Description |
|---|---|---|---|---|
Idempotency-Key | header | oui | string | 8 à 64 caractères, unique par opération. Même clé + même corps sous 24 h = même réponse. motif |
Corps de la requête
application/json — WebhookEndpointCreate (obligatoire)
{
"url": "https://hooks.conciergerie.example.com/kelki",
"events": [
"request.status_changed"
],
"description": "Statuts des demandes"
}Réponses
| Code | Description | Contenu |
|---|---|---|
201 | Adresse créée. | application/json WebhookEndpointCreated |
400 | Requête mal formée (JSON invalide, paramètre inconnu, corps trop gros). | application/problem+json Problem |
401 | Identifiants absents, invalides, expirés ou révoqués. | application/problem+json Problem |
403 | Portée manquante, compte non autorisé en live, pays non ouvert, compte suspendu. | application/problem+json Problem |
422 | Valeur refusée par les règles du formulaire (listes fermées, lieu, coordonnées, accord, limites anti-abus). | application/problem+json Problem |
Exemple de réponse
{
"id": "we_01JC00000000000000000000AA",
"url": "https://hooks.conciergerie.example.com/kelki",
"events": [
"request.status_changed"
],
"description": "Statuts des demandes",
"mode": "test",
"enabled": true,
"created_at": "2026-11-11T09:00:00Z",
"secret": "whsec_EXEMPLE_NE_PAS_UTILISER_000000000000"
}GET /webhook-endpoints/{endpoint_id}
Lire une adresse de webhook
Authentification : clé API (Authorization: Bearer kk_…) ou jeton OAuth 2.0 (portée webhooks.manage).
Paramètres
| Nom | Où | Requis | Type | Description |
|---|---|---|---|---|
endpoint_id | path | oui | string | motif |
Réponses
| Code | Description | Contenu |
|---|---|---|
200 | L'adresse (sans le secret). | application/json WebhookEndpoint |
401 | Identifiants absents, invalides, expirés ou révoqués. | application/problem+json Problem |
404 | Ressource inconnue, ou appartenant à un autre compte ou à un autre mode (même réponse). | application/problem+json Problem |
DELETE /webhook-endpoints/{endpoint_id}
Supprimer une adresse de webhook
Authentification : clé API (Authorization: Bearer kk_…) ou jeton OAuth 2.0 (portée webhooks.manage).
Paramètres
| Nom | Où | Requis | Type | Description |
|---|---|---|---|---|
endpoint_id | path | oui | string | motif |
Réponses
POST /webhook-endpoints/{endpoint_id}/test
Envoyer un événement « ping »
Authentification : clé API (Authorization: Bearer kk_…) ou jeton OAuth 2.0 (portée webhooks.manage).
Paramètres
| Nom | Où | Requis | Type | Description |
|---|---|---|---|---|
endpoint_id | path | oui | string | motif |
Réponses
| Code | Description | Contenu |
|---|---|---|
202 | Ping mis en file d'envoi. | |
401 | Identifiants absents, invalides, expirés ou révoqués. | application/problem+json Problem |
404 | Ressource inconnue, ou appartenant à un autre compte ou à un autre mode (même réponse). | application/problem+json Problem |
429 | Débit ou quota dépassé. | application/problem+json Problem |
POST /webhook-endpoints/{endpoint_id}/rotate-secret
Remplacer le secret de signature
Pendant 24 heures, chaque événement porte deux signatures (v1= ancien et nouveau secret).
Authentification : clé API (Authorization: Bearer kk_…) ou jeton OAuth 2.0 (portée webhooks.manage).
Paramètres
| Nom | Où | Requis | Type | Description |
|---|---|---|---|---|
endpoint_id | path | oui | string | motif |
Réponses
| Code | Description | Contenu |
|---|---|---|
200 | Nouveau secret, montré une seule fois. | application/json WebhookEndpointCreated |
401 | Identifiants absents, invalides, expirés ou révoqués. | application/problem+json Problem |
404 | Ressource inconnue, ou appartenant à un autre compte ou à un autre mode (même réponse). | application/problem+json Problem |
ÉVÉNEMENT request.status_changed
Changement de statut d'une demande
Envoyé à chaque changement de statut. Vérifiez Kelki-Signature : t=<horodatage unix>,v1=<HMAC-SHA256 hex> calculé sur "<t>.<corps brut>" avec le secret whsec_…, comparaison à durée constante, tolérance 5 minutes. Dédoublonnez sur Kelki-Event-Id. Répondez 2xx en moins de 5 secondes ; sinon nouvel essai à 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h.
Paramètres
| Nom | Où | Requis | Type | Description |
|---|---|---|---|---|
Kelki-Signature | header | oui | string | |
Kelki-Event-Id | header | oui | string |
Corps de la requête
application/json — WebhookEvent (obligatoire)
{
"id": "evt_01JC0000000000000000000003",
"type": "request.status_changed",
"api_version": "1",
"mode": "live",
"created_at": "2026-11-11T10:15:41Z",
"data": {
"request": {
"id": "req_01JC00000000000000000000RQ",
"object": "request",
"mode": "live",
"status": "sold",
"status_changed_at": "2026-11-11T10:15:40Z",
"reference": "resa-2026-0042",
"country": "FR",
"trade": {
"id": "plombier",
"name": "Plombier"
},
"service": "Recherche de fuite",
"delay": "Dès que possible",
"place": {
"id": "fr-creteil-94000",
"label": "Créteil (94000)"
},
"created_at": "2026-11-11T09:41:58Z"
}
}
}Réponses
| Code | Description | Contenu |
|---|---|---|
2XX | Événement reçu. | |
4XX | Refusé par le partenaire (nouvel essai selon le calendrier, sauf 410 qui désactive l'adresse). |
Schémas
WebhookEndpointList
Type : ListMeta et object
Problem
Détails d'un problème (RFC 9457), avec des membres d'extension.
| Champ | Type | Requis | Description |
|---|---|---|---|
type | string (uri) | oui | URI stable du type de problème ; elle mène à sa documentation. |
title | string | oui | |
status | integer | oui | min. 400 · max. 599 |
detail | string | non | |
instance | string (uri-reference) | non | |
code | string | oui | Code stable, lisible par une machine. valeurs : |
request_id | string | oui | |
errors | tableau de FieldError | non |
WebhookEndpointCreate
| Champ | Type | Requis | Description |
|---|---|---|---|
url | string (uri) | oui | max. 500 car. · motif |
events | tableau de string | oui | min. 1 él. |
description | string | non | max. 120 car. |
WebhookEndpointCreated
Type : WebhookEndpoint et object
WebhookEndpoint
| Champ | Type | Requis | Description |
|---|---|---|---|
id | string | oui | |
url | string (uri) | oui | |
events | tableau de string | oui | |
description | string | non | |
mode | string | oui | valeurs : |
enabled | boolean | oui | |
created_at | string (date-time) | oui | |
disabled_reason | string | null | non | valeurs : |
WebhookEvent
| Champ | Type | Requis | Description |
|---|---|---|---|
id | string | oui | |
type | string | oui | valeurs : |
api_version | string | oui | |
mode | string | oui | valeurs : |
created_at | string (date-time) | oui | |
data | object | oui |
ListMeta
| Champ | Type | Requis | Description |
|---|---|---|---|
object | string | oui | valeur : |
has_more | boolean | oui | |
next_cursor | string | null | oui |
FieldError
| Champ | Type | Requis | Description |
|---|---|---|---|
pointer | string | oui | JSON Pointer (RFC 6901) du champ en cause. |
detail | string | oui | |
allowed | tableau de string | non | Valeurs acceptées, quand la liste est fermée. |