# Webhooks (reference) Subscriptions to status changes, signed with HMAC-SHA256. Base URL: `https://kelki.ai/api/v1`. - GET /webhook-endpoints — List your webhook endpoints - POST /webhook-endpoints — Declare a webhook endpoint - GET /webhook-endpoints/{endpoint_id} — Read a webhook endpoint - DELETE /webhook-endpoints/{endpoint_id} — Delete a webhook endpoint - POST /webhook-endpoints/{endpoint_id}/test — Send a “ping” event - POST /webhook-endpoints/{endpoint_id}/rotate-secret — Replace the signing secret ## GET `/webhook-endpoints` List your webhook endpoints Authentication: API key (`Authorization: Bearer kk_…`) or OAuth 2.0 token (scope `webhooks.manage`). ### Responses | Code | Description | Content | | `200` | Endpoints declared for the current mode. | `application/json` WebhookEndpointList | | `401` | Missing, invalid, expired or revoked credentials. | `application/problem+json` Problem | ## POST `/webhook-endpoints` Declare a webhook endpoint HTTPS only, public domain name (no IP address), valid certificate. The secret is shown only once. Authentication: API key (`Authorization: Bearer kk_…`) or OAuth 2.0 token (scope `webhooks.manage`). ### Parameters | Name | In | Required | Type | Description | | `Idempotency-Key` | header | yes | string | 8 to 64 characters, unique per operation. Same key + same body within 24 h = same response. pattern `^[A-Za-z0-9_\-]{8,64}$` | ### Request body `application/json` — WebhookEndpointCreate (required) ``` { "url": "https://hooks.conciergerie.example.com/kelki", "events": [ "request.status_changed" ], "description": "Statuts des demandes" } ``` ### Responses | Code | Description | Content | | `201` | Endpoint created. `secret` will never appear again. | `application/json` WebhookEndpointCreated | | `400` | Malformed request (invalid JSON, unknown parameter, body too large). | `application/problem+json` Problem | | `401` | Missing, invalid, expired or revoked credentials. | `application/problem+json` Problem | | `403` | Missing scope, account not enabled for live, country not open, account suspended. | `application/problem+json` Problem | | `422` | Value refused by the form's rules (closed lists, place, contact details, consent, anti-abuse limits). | `application/problem+json` Problem | ### Response example ``` { "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}` Read a webhook endpoint Authentication: API key (`Authorization: Bearer kk_…`) or OAuth 2.0 token (scope `webhooks.manage`). ### Parameters | Name | In | Required | Type | Description | | `endpoint_id` | path | yes | string | pattern `^we_[0-9A-Z]{26}$` | ### Responses | Code | Description | Content | | `200` | The endpoint (without the secret). | `application/json` WebhookEndpoint | | `401` | Missing, invalid, expired or revoked credentials. | `application/problem+json` Problem | | `404` | Unknown resource, or one belonging to another account or another mode (same response). | `application/problem+json` Problem | ## DELETE `/webhook-endpoints/{endpoint_id}` Delete a webhook endpoint Authentication: API key (`Authorization: Bearer kk_…`) or OAuth 2.0 token (scope `webhooks.manage`). ### Parameters | Name | In | Required | Type | Description | | `endpoint_id` | path | yes | string | pattern `^we_[0-9A-Z]{26}$` | ### Responses | Code | Description | Content | | `204` | Deleted. | | | `401` | Missing, invalid, expired or revoked credentials. | `application/problem+json` Problem | | `404` | Unknown resource, or one belonging to another account or another mode (same response). | `application/problem+json` Problem | ## POST `/webhook-endpoints/{endpoint_id}/test` Send a “ping” event Authentication: API key (`Authorization: Bearer kk_…`) or OAuth 2.0 token (scope `webhooks.manage`). ### Parameters | Name | In | Required | Type | Description | | `endpoint_id` | path | yes | string | pattern `^we_[0-9A-Z]{26}$` | ### Responses | Code | Description | Content | | `202` | Ping queued for delivery. | | | `401` | Missing, invalid, expired or revoked credentials. | `application/problem+json` Problem | | `404` | Unknown resource, or one belonging to another account or another mode (same response). | `application/problem+json` Problem | | `429` | Rate or quota exceeded. | `application/problem+json` Problem | ## POST `/webhook-endpoints/{endpoint_id}/rotate-secret` Replace the signing secret For 24 hours, each event carries two signatures (`v1=` old and new secret). Authentication: API key (`Authorization: Bearer kk_…`) or OAuth 2.0 token (scope `webhooks.manage`). ### Parameters | Name | In | Required | Type | Description | | `endpoint_id` | path | yes | string | pattern `^we_[0-9A-Z]{26}$` | ### Responses | Code | Description | Content | | `200` | New secret, shown only once. | `application/json` WebhookEndpointCreated | | `401` | Missing, invalid, expired or revoked credentials. | `application/problem+json` Problem | | `404` | Unknown resource, or one belonging to another account or another mode (same response). | `application/problem+json` Problem | ## EVENT `request.status_changed` Status change of a request Sent on every status change. Check `Kelki-Signature`: `t=,v1=` computed over `"."` with the `whsec_…` secret, constant-time comparison, 5-minute tolerance. Deduplicate on `Kelki-Event-Id`. Reply 2xx within 5 seconds; otherwise new attempt after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h. ### Parameters | Name | In | Required | Type | Description | | `Kelki-Signature` | header | yes | string | | | `Kelki-Event-Id` | header | yes | string | | ### Request body `application/json` — WebhookEvent (required) ``` { "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" } } } ``` ### Responses | Code | Description | Content | | `2XX` | Event received. | | | `4XX` | Refused by the partner (new attempt according to the schedule, except 410 which disables the endpoint). | | ## Schemas ### `WebhookEndpointList` Type: ListMeta and object ### `Problem` Problem details (RFC 9457), with extension members. | Field | Type | Required | Description | | `type` | string (uri) | yes | Stable URI of the problem type; it leads to its documentation. | | `title` | string | yes | | | `status` | integer | yes | min. 400 · max. 599 | | `detail` | string | no | | | `instance` | string (uri-reference) | no | | | `code` | string | yes | Stable, machine-readable code. values: `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 | yes | | | `errors` | array of FieldError | no | | ### `WebhookEndpointCreate` | Field | Type | Required | Description | | `url` | string (uri) | yes | max. 500 chars · pattern `^https://` | | `events` | array of string | yes | min. 1 items | | `description` | string | no | max. 120 chars | ### `WebhookEndpointCreated` Type: WebhookEndpoint and object ### `WebhookEndpoint` | Field | Type | Required | Description | | `id` | string | yes | | | `url` | string (uri) | yes | | | `events` | array of string | yes | | | `description` | string | no | | | `mode` | string | yes | values: `test`, `live` | | `enabled` | boolean | yes | | | `created_at` | string (date-time) | yes | | | `disabled_reason` | string | null | no | values: `too_many_failures`, `gone`, `` | ### `WebhookEvent` | Field | Type | Required | Description | | `id` | string | yes | | | `type` | string | yes | values: `request.status_changed`, `ping` | | `api_version` | string | yes | | | `mode` | string | yes | values: `test`, `live` | | `created_at` | string (date-time) | yes | | | `data` | object | yes | | ### `ListMeta` | Field | Type | Required | Description | | `object` | string | yes | value: `list` | | `has_more` | boolean | yes | | | `next_cursor` | string | null | yes | | ### `FieldError` | Field | Type | Required | Description | | `pointer` | string | yes | JSON Pointer (RFC 6901) of the field at fault. | | `detail` | string | yes | | | `allowed` | array of string | no | Accepted values, when the list is closed. | ## About this page - URL : https://kelki.ai/developers/en/reference/webhooks/ - Language : en - fr : https://kelki.ai/developers/fr/reference/webhooks/ - en : https://kelki.ai/developers/en/reference/webhooks/ - x-default : https://kelki.ai/developers/ - Portal : https://kelki.ai/developers/llms.txt