Consulter l'état du secret de signature d'un webhook

Renvoie un résumé non sensible de l'état du secret de signature d'un webhook (préfixe, dernière rotation, fenêtre de grâce) sans jamais exposer la valeur du secret.

2 min de lectureTélécharger en PDF

Réponse exemple

{
  "is_active": true,
  "webhook_id": "wh_3f9a2c7e1b4d",
  "grace_until": "2026-06-08T09:14:00.000Z",
  "webhook_name": "Notifications production",
  "recommendation": null,
  "last_rotated_at": "2026-05-20T09:14:00.000Z",
  "grace_window_active": true,
  "current_secret_prefix": "whsec_a1b2c3…",
  "previous_secret_prefix": "whsec_9f8e7d…",
  "days_since_last_rotation": 16
}

GET/v1/webhooks/{id}/secret-statusRésumé non sensible de l'état du secret de signature d'un webhook.

Cet endpoint renvoie un résumé non sensible de l'état du secret de signature utilisé pour vérifier l'authenticité des livraisons d'un webhook. Il ne renvoie jamais la valeur du secret : seuls des préfixes tronqués (par exemple whsec_a1b2c3…) sont exposés, afin de vous permettre d'identifier visuellement quel secret est actif sans pouvoir le reconstituer. La réponse couvre le secret courant, le secret précédent (uniquement pendant la fenêtre de grâce), la date de dernière rotation, le nombre de jours écoulés depuis cette rotation, et une recommandation lorsque le secret n'a pas été tourné depuis plus de 180 jours.

Le webhook est recherché par son identifiant (id, dernier segment du chemin avant secret-status) et restreint au workspace de la clé API : un webhook appartenant à un autre workspace renvoie une erreur 404. Le champ previous_secret_prefix et le champ grace_until ne sont renseignés que si une fenêtre de grâce est encore active (c'est-à-dire si secret_grace_until est dans le futur), période durant laquelle l'ancien secret reste valable en parallèle du nouveau.

Authentification

Cet endpoint nécessite une clé API valide disposant du scope webhooks:manage. Transmettez la clé via l'en-tête Authorization: Bearer cof_live_... (ou cof_test_..., cof_rk_live_..., cof_mcp_live_...). Une clé dépourvue de ce scope reçoit une erreur 403 avec le code scope_missing.

Paramètres de requête

Paramètre	Type	Requis	Description
id	string (chemin)	Oui	Identifiant du webhook dont on consulte l'état du secret. Extrait du chemin de l'URL (avant-dernier segment).

Cet endpoint n'accepte aucun paramètre de requête en query string ni aucun corps de requête. L'idempotence est désactivée (skipIdempotency) car il s'agit d'une lecture pure.

Réponse

La réponse 200 est un objet JSON décrivant l'état du secret. Les champs clés sont les suivants.

Champ	Type	Description
webhook_id	string	Identifiant du webhook.
webhook_name	string	Nom lisible du webhook.
is_active	boolean	Indique si le webhook est actif.
current_secret_prefix	string \| null	Préfixe tronqué du secret courant (ex. `whsec_a1b2c3…`), ou `null` si aucun secret n'est défini.
previous_secret_prefix	string \| null	Préfixe tronqué du secret précédent, renseigné uniquement si la fenêtre de grâce est active, sinon `null`.
last_rotated_at	string (ISO 8601) \| null	Horodatage de la dernière rotation du secret, ou `null` si jamais tourné.
days_since_last_rotation	number \| null	Nombre de jours entiers écoulés depuis la dernière rotation, ou `null` si jamais tourné.
grace_window_active	boolean	Indique si une fenêtre de grâce est en cours (ancien secret encore valable).
grace_until	string (ISO 8601) \| null	Date d'expiration de la fenêtre de grâce, renseignée uniquement si elle est active, sinon `null`.
recommendation	string \| null	Recommandation textuelle si le secret n'a pas été tourné depuis plus de 180 jours, sinon `null`.

Erreurs

Code	Quand	Résolution
401 missing_api_key	En-tête `Authorization` absent.	Ajoutez `Authorization: Bearer cof_live_...`.
401 invalid_api_key	Clé API invalide, malformée, révoquée ou expirée.	Vérifiez le préfixe et la validité de la clé.
403 scope_missing	La clé ne possède pas le scope `webhooks:manage`.	Émettez une clé incluant le scope `webhooks:manage`.
404 not_found	Aucun webhook avec cet `id` dans le workspace de la clé.	Vérifiez l'identifiant et que le webhook appartient au bon workspace.
429 rate_limited	Quota de requêtes par minute dépassé pour le workspace.	Respectez l'en-tête `Retry-After` avant de réessayer.
500 internal_error	Erreur interne lors de la lecture en base.	Réessayez ; si le problème persiste, contactez le support avec le `request_id`.

Voir aussi

POST /v1/webhooks/{id}/rotate-secret — faire tourner le secret de signature et ouvrir une fenêtre de grâce.
GET /v1/webhooks/{id} — consulter la configuration complète d'un webhook.
GET /v1/webhooks — lister les webhooks du workspace.