Webhooks (reference)
Subscriptions to status changes, signed with HMAC-SHA256.
Base URL: https://kelki.ai/api/v1.
GET /webhook-endpoints— List your webhook endpointsPOST /webhook-endpoints— Declare a webhook endpointGET /webhook-endpoints/{endpoint_id}— Read a webhook endpointDELETE /webhook-endpoints/{endpoint_id}— Delete a webhook endpointPOST /webhook-endpoints/{endpoint_id}/test— Send a “ping” eventPOST /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 |
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. | 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 |
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 |
Responses
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 |
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 |
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=<unix timestamp>,v1=<HMAC-SHA256 hex> computed over "<t>.<raw body>" 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: |
request_id | string | yes | |
errors | array of FieldError | no |
WebhookEndpointCreate
| Field | Type | Required | Description |
|---|---|---|---|
url | string (uri) | yes | max. 500 chars · pattern |
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: |
enabled | boolean | yes | |
created_at | string (date-time) | yes | |
disabled_reason | string | null | no | values: |
WebhookEvent
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
type | string | yes | values: |
api_version | string | yes | |
mode | string | yes | values: |
created_at | string (date-time) | yes | |
data | object | yes |
ListMeta
| Field | Type | Required | Description |
|---|---|---|---|
object | string | yes | value: |
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. |