Aller au contenu
KelkiDéveloppeurs

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

Authentification : clé API (Authorization: Bearer kk_…) ou jeton OAuth 2.0 (portée webhooks.manage).

Réponses

CodeDescriptionContenu
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

NomOùRequisTypeDescription
Idempotency-Keyheaderouistring

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

CodeDescriptionContenu
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

NomOùRequisTypeDescription
endpoint_idpathouistring

motif ^we_[0-9A-Z]{26}$

Réponses

CodeDescriptionContenu
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

NomOùRequisTypeDescription
endpoint_idpathouistring

motif ^we_[0-9A-Z]{26}$

Réponses

CodeDescriptionContenu
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

NomOùRequisTypeDescription
endpoint_idpathouistring

motif ^we_[0-9A-Z]{26}$

Réponses

CodeDescriptionContenu
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

NomOùRequisTypeDescription
endpoint_idpathouistring

motif ^we_[0-9A-Z]{26}$

Réponses

CodeDescriptionContenu
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

NomOùRequisTypeDescription
Kelki-Signatureheaderouistring
Kelki-Event-Idheaderouistring

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

CodeDescriptionContenu
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.

ChampTypeRequisDescription
typestring (uri)oui

URI stable du type de problème ; elle mène à sa documentation.

titlestringoui
statusintegeroui

min. 400 · max. 599

detailstringnon
instancestring (uri-reference)non
codestringoui

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_idstringoui
errorstableau de FieldErrornon

WebhookEndpointCreate

ChampTypeRequisDescription
urlstring (uri)oui

max. 500 car. · motif ^https://

eventstableau de stringoui

min. 1 él.

descriptionstringnon

max. 120 car.

WebhookEndpointCreated

Type : WebhookEndpoint et object

WebhookEndpoint

ChampTypeRequisDescription
idstringoui
urlstring (uri)oui
eventstableau de stringoui
descriptionstringnon
modestringoui

valeurs : test, live

enabledbooleanoui
created_atstring (date-time)oui
disabled_reasonstring | nullnon

valeurs : too_many_failures, gone,

WebhookEvent

ChampTypeRequisDescription
idstringoui
typestringoui

valeurs : request.status_changed, ping

api_versionstringoui
modestringoui

valeurs : test, live

created_atstring (date-time)oui
dataobjectoui

ListMeta

ChampTypeRequisDescription
objectstringoui

valeur : list

has_morebooleanoui
next_cursorstring | nulloui

FieldError

ChampTypeRequisDescription
pointerstringoui

JSON Pointer (RFC 6901) du champ en cause.

detailstringoui
allowedtableau de stringnon

Valeurs acceptées, quand la liste est fermée.