Effectuer une rotation du secret de signature sans interruption

Renouvelez le secret HMAC d'un Webhook Coffrify en conservant l'ancien valide pendant une fenêtre de grâce configurable, pour ne perdre aucune livraison.

Télécharger en PDF

Chaque Webhook Coffrify est signé avec un secret de la forme whsec_<hex64>. Lorsque vous effectuez une rotation, l'API génère un nouveau secret et conserve l'ancien valide pendant une fenêtre de grâce configurable (par défaut 24 h, maximum 168 h soit 7 jours). Pendant cette fenêtre, la couche de livraison accepte les deux secrets, ce qui vous permet de mettre à jour votre infrastructure réceptrice sans perdre aucune notification. Vous pouvez également interroger le statut du secret à tout moment sans jamais exposer sa valeur.

POST/v1/webhooks/{id}/rotate-secretGénère un nouveau secret de signature et archive l'ancien pour la durée de la fenêtre de grâce.GET/v1/webhooks/{id}/secret-statusRetourne l'état du secret (préfixe, date de rotation, fenêtre de grâce active) sans jamais exposer la valeur.

Authentification

Ces deux endpoints requièrent une clé API portant le scope webhooks:manage. Transmettez votre clé dans l'en-tête Authorization: Bearer <clé>. Les clés de test commencent par cof_test_…, les clés de production par cof_live_….

Corps de la requête (POST rotate-secret)

Le corps précise surtout la fenêtre de grâce pendant laquelle l'ancien secret reste accepté. Le tableau ci-dessous détaille les champs acceptés.

Champ	Type	Requis	Description
grace_window_hours	integer	Non	Durée (en heures) pendant laquelle l'ancien secret reste valide. Valeur par défaut : `24`. Plage autorisée : 1 à 168.

Exemple d'appel

L'exemple ci-dessous effectue une rotation du secret, puis vérifie l'état courant. Choisissez votre langage.

curl -X POST https://api.coffrify.com/v1/webhooks/wh_01HXYZ/rotate-secret \
  -H "Authorization: Bearer cof_live_…" \
  -H "Content-Type: application/json" \
  -d '{"grace_window_hours": 48}'

Réponses

La rotation renvoie le nouveau secret (whsec_…), à conserver immédiatement, tandis que l'endpoint de statut ne révèle jamais la valeur, seulement les métadonnées (préfixe, fenêtre de grâce).

{
  "webhook_id": "wh_01HXYZ",
  "secret": "whsec_a3f2e1c9b8d74f0a1e2c3b4d5e6f7089abcdef0123456789abcdef0123456789",
  "rotated_at": "2026-06-06T14:32:00.000Z",
  "secret_grace_until": "2026-06-08T14:32:00.000Z",
  "grace_window_hours": 48
}

Erreurs

Les erreurs portent sur un webhook introuvable, le scope webhooks:manage manquant ou une fenêtre de grâce déjà active. Le tableau ci-dessous indique la résolution.

Code HTTP	Code d'erreur	Quand	Résolution
400	`validation_error`	`grace_window_hours` est inférieur à 1 ou supérieur à 168.	Utilisez une valeur entre 1 et 168 inclus.
401	`missing_api_key` / `invalid_api_key`	Aucune clé fournie ou clé invalide.	Vérifiez l'en-tête `Authorization: Bearer cof_live_…`.
403	`scope_missing`	La clé ne porte pas le scope `webhooks:manage`.	Émettez une nouvelle clé avec le scope requis depuis la console.
404	`not_found`	L'identifiant de Webhook n'existe pas dans l'espace de travail.	Vérifiez l'`id` transmis et le workspace associé à votre clé.
429	`rate_limited`	Quota de requêtes write dépassé pour la minute en cours.	Attendez la valeur indiquée dans l'en-tête `Retry-After`.
500	`internal_error`	Erreur de base de données lors de la mise à jour du secret.	Réessayez. Si le problème persiste, contactez le support avec le `X-Request-Id`.

Bonnes pratiques de rotation

1. Appelez GET /v1/webhooks/{id}/secret-status avant toute rotation pour connaître l'état courant et vérifier qu'aucune fenêtre de grâce n'est déjà active. 2. Choisissez une grace_window_hours suffisante pour couvrir le temps de déploiement de vos consommateurs (recommandation : 48 h en production). 3. Stockez le nouveau secret dans votre gestionnaire de secrets (Vault, AWS Secrets Manager, Vercel Environment Variables) avant la fin de la fenêtre de grâce. 4. Pendant la fenêtre, vérifiez les deux signatures côté récepteur : HMAC du nouveau secret ET de l'ancien, et acceptez si l'une est valide. 5. Après expiration de la grâce, previous_secret_prefix sera null dans secret-status : l'ancien secret est définitivement révoqué. 6. Le champ recommendation de secret-status vous alerte automatiquement lorsque le secret n'a pas été renouvelé depuis plus de 180 jours.

Voir aussi

Créer un Webhook
Vérifier la signature HMAC d'une livraison
Relancer une livraison échouée
Référence : POST /v1/webhooks/{id}/rotate-secret
Référence : GET /v1/webhooks/{id}/secret-status

Continuer

Autres tutoriels à suivre

📥Recevoir des fichiers en 5 min (no-code)→🚀Construire un agent qui crée et livre des transferts automatiquement→✅Implémenter un workflow d'approbation de transfert→