# 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 webhooks - POST /webhook-endpoints — Déclarer une adresse de webhook - GET /webhook-endpoints/{endpoint_id} — Lire une adresse de webhook - DELETE /webhook-endpoints/{endpoint_id} — Supprimer une adresse de webhook - POST /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 `^[A-Za-z0-9_\-]{8,64}$` | ### 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. `secret` n'apparaîtra plus jamais. | `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 `^we_[0-9A-Z]{26}$` | ### 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 `^we_[0-9A-Z]{26}$` | ### Réponses | Code | Description | Contenu | | `204` | Supprimée. | | | `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 | ## 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 `^we_[0-9A-Z]{26}$` | ### 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 `^we_[0-9A-Z]{26}$` | ### 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=,v1=` calculé sur `"."` 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 : `invalid_json`, `invalid_parameter`, `payload_too_large`, `unsupported_media_type`, `invalid_credentials`, `expired_token`, `insufficient_scope`, `live_not_enabled`, `account_suspended`, `country_not_available`, `trade_not_available`, `not_found`, `invalid_state`, `idempotency_in_progress`, `idempotency_key_reused`, `validation_failed`, `consent_missing`, `consent_version_outdated`, `contact_limit_reached`, `duplicate_request`, `rate_limited`, `quota_exceeded`, `agent_paused`, `live_creation_paused`, `service_unavailable`, `internal_error` | | `request_id` | string | oui | | | `errors` | tableau de FieldError | non | | ### `WebhookEndpointCreate` | Champ | Type | Requis | Description | | `url` | string (uri) | oui | max. 500 car. · motif `^https://` | | `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 : `test`, `live` | | `enabled` | boolean | oui | | | `created_at` | string (date-time) | oui | | | `disabled_reason` | string | null | non | valeurs : `too_many_failures`, `gone`, `` | ### `WebhookEvent` | Champ | Type | Requis | Description | | `id` | string | oui | | | `type` | string | oui | valeurs : `request.status_changed`, `ping` | | `api_version` | string | oui | | | `mode` | string | oui | valeurs : `test`, `live` | | `created_at` | string (date-time) | oui | | | `data` | object | oui | | ### `ListMeta` | Champ | Type | Requis | Description | | `object` | string | oui | valeur : `list` | | `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. | ## Sur cette page - URL : https://kelki.ai/developers/fr/reference/webhooks/ - Langue : fr - fr : https://kelki.ai/developers/fr/reference/webhooks/ - en : https://kelki.ai/developers/en/reference/webhooks/ - x-default : https://kelki.ai/developers/ - Portail : https://kelki.ai/developers/llms.txt