Skip to content
KelkiDevelopers

Webhooks (reference)

Subscriptions to status changes, signed with HMAC-SHA256.

Base URL: https://kelki.ai/api/v1.

GET /webhook-endpoints

List your webhook endpoints

Authentication: API key (Authorization: Bearer kk_…) or OAuth 2.0 token (scope webhooks.manage).

Responses

CodeDescriptionContent
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

NameInRequiredTypeDescription
Idempotency-Keyheaderyesstring

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

CodeDescriptionContent
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

NameInRequiredTypeDescription
endpoint_idpathyesstring

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

Responses

CodeDescriptionContent
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

NameInRequiredTypeDescription
endpoint_idpathyesstring

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

Responses

CodeDescriptionContent
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

NameInRequiredTypeDescription
endpoint_idpathyesstring

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

Responses

CodeDescriptionContent
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

NameInRequiredTypeDescription
endpoint_idpathyesstring

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

Responses

CodeDescriptionContent
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

NameInRequiredTypeDescription
Kelki-Signatureheaderyesstring
Kelki-Event-Idheaderyesstring

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

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

FieldTypeRequiredDescription
typestring (uri)yes

Stable URI of the problem type; it leads to its documentation.

titlestringyes
statusintegeryes

min. 400 · max. 599

detailstringno
instancestring (uri-reference)no
codestringyes

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_idstringyes
errorsarray of FieldErrorno

WebhookEndpointCreate

FieldTypeRequiredDescription
urlstring (uri)yes

max. 500 chars · pattern ^https://

eventsarray of stringyes

min. 1 items

descriptionstringno

max. 120 chars

WebhookEndpointCreated

Type: WebhookEndpoint and object

WebhookEndpoint

FieldTypeRequiredDescription
idstringyes
urlstring (uri)yes
eventsarray of stringyes
descriptionstringno
modestringyes

values: test, live

enabledbooleanyes
created_atstring (date-time)yes
disabled_reasonstring | nullno

values: too_many_failures, gone,

WebhookEvent

FieldTypeRequiredDescription
idstringyes
typestringyes

values: request.status_changed, ping

api_versionstringyes
modestringyes

values: test, live

created_atstring (date-time)yes
dataobjectyes

ListMeta

FieldTypeRequiredDescription
objectstringyes

value: list

has_morebooleanyes
next_cursorstring | nullyes

FieldError

FieldTypeRequiredDescription
pointerstringyes

JSON Pointer (RFC 6901) of the field at fault.

detailstringyes
allowedarray of stringno

Accepted values, when the list is closed.