Ajouter un point de terminaison webhook

POST /v1/webhook-endpoints · autorisation webhook-endpoints:write · tous les forfaits

Ajoute un point de terminaison qui reçoit les événements de l'environnement, signés selon le schéma Standard Webhooks v1. Les livraisons sont effectuées au moins une fois : dédupliquez-les avec l'en-tête webhook-id.

Secret de signature. La réponse contient signing_secret (idp_whsec_…) une seule fois, avec Cache-Control: no-store. Il ne peut pas être récupéré à nouveau ; enregistrez-le immédiatement. Une requête répétée avec la même Idempotency-Key renvoie le point de terminaison sans le secret et avec secret_redacted: true. Utilisez Renouveler le secret de signature s'il est perdu ou compromis.
URL. https uniquement, sans port ou avec le port 443, sans informations utilisateur ni fragment, sans adresse IP littérale, au maximum 2 048 caractères. Les redirections ne sont pas suivies.
Événements. event_types liste les types d'événements du catalogue ; une liste vide signifie tous les types, à l'exception des types à fort volume.
Limite. Un environnement peut avoir au maximum 3 points de terminaison activés avec le forfait Free, 20 avec Startup, 20 avec Business ou 50 avec Enterprise.

Requête

Champ	Type	Obligatoire	Description
`url`	string	oui	URL du récepteur (règles ci-dessus).
`key`	string	non	Clé stable, unique dans l'environnement : `[a-z0-9][a-z0-9_-]{0,63}`. Par défaut `endpoint-<8 derniers caractères de l'identifiant>`.
`description`	string	non	500 caractères au maximum.
`event_types`	array	non	Types d'événements du catalogue, 100 au maximum, sans doublons. Vide ou absent : tous les types, à l'exception des types à fort volume.
`event_schema_versions`	object	non	Type d'événement → version du schéma. Un type non listé est envoyé avec sa version prise en charge la plus ancienne.
`payload_mode`	string	non	`thin` (par défaut : identifiants, noms des champs modifiés et champs d'état, sans données personnelles) ou `full` (la représentation de la ressource dans l'API de gestion).
`rate_limit_per_second`	integer	non	De 1 à 1 000 livraisons par seconde vers ce point de terminaison ; 50 par défaut.
`status`	string	non	`enabled` (par défaut) ou `disabled_by_user`.
`Idempotency-Key`	header	non	Rejoue la réponse (sans le secret) pour une requête répétée avec la même clé.

{
  "url": "https://hooks.example.com/keenauth",
  "key": "crm-sync",
  "description": "CRM sync",
  "event_types": ["user.created", "user.updated"]
}

Réponse

201 Created avec le point de terminaison, ETag défini sur sa version, et le secret. Les autres champs sont décrits dans Obtenir un point de terminaison webhook.

{
  "id": "whe_01k8a3m5q7t9v1w3x5y7z9b2c4",
  "key": "crm-sync",
  "url": "https://hooks.example.com/keenauth",
  "description": "CRM sync",
  "event_types": ["user.created", "user.updated"],
  "event_schema_versions": {},
  "payload_mode": "thin",
  "status": "enabled",
  "rate_limit_per_second": 50,
  "previous_secret_expires_at": null,
  "last_success_at": null,
  "failing_since": null,
  "version": 1,
  "created_at": "2026-10-26T09:00:00Z",
  "updated_at": "2026-10-26T09:00:00Z",
  "signing_secret": "idp_whsec_<secret>"
}

Erreurs

HTTP	code	Quand
400	`unknown_field`	Le corps contient un champ qui n'est pas listé ci-dessus.
403	`quota_exceeded`	L'environnement a déjà le nombre de points de terminaison activés de son forfait, ou son forfait est inconnu.
409	`conflict`	Un autre point de terminaison de l'environnement possède cette `key`.
422	`validation_failed`	`/url required`, `/url invalid_webhook_url`, `/key invalid`, `/description too_long`, `/event_types unknown_event_type`, `/event_types duplicate`, `/event_types too_many`, `/event_schema_versions unsupported_schema_version`, `/payload_mode invalid`, `/rate_limit_per_second out_of_range`, `/status invalid`.
422	`idempotency_key_reuse`	La `Idempotency-Key` a été utilisée avec une requête différente.
401	`unauthenticated`	L'identifiant est absent, invalide ou révoqué.
403	`insufficient_permissions`	L'identifiant ne dispose pas de `webhook-endpoints:write`.
429	`rate_limited`	La limite de débit a été dépassée ; réessayez après la durée indiquée par `Retry-After`.
503	`service_unavailable`	L'administration des webhooks est temporairement indisponible ; réessayez après la durée indiquée par `Retry-After`.

Exemple

curl -X POST https://api.eu.keenauth.com/v1/webhook-endpoints \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b2d4f6a-1c3e-4a5b-8d7f-0e2c4a6b8d1f" \
  -d '{"url":"https://hooks.example.com/keenauth","key":"crm-sync","event_types":["user.created","user.updated"]}'

CLI : keenauth webhook-endpoints create --url https://hooks.example.com/keenauth --key crm-sync --event-types user.created,user.updated