Se connecterCommencer gratuitement
Référence APIFaire pivoter le secret de signature d'un webhook
POST/v1/webhooks/{id}/rotate-secret

Faire pivoter le secret de signature d'un webhook

Génère un nouveau secret de signature pour un webhook tout en laissant l'ancien valide pendant une fenêtre de grâce configurable.

2 min de lectureTélécharger en PDF

Requête exemple

{
  "grace_window_hours": 48
}

Réponse exemple

{
  "secret": "whsec_3a9f1c08d2e74b65a1f0c9d3e8b27a4f6c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f",
  "rotated_at": "2026-06-05T10:42:11.183Z",
  "webhook_id": "wh_9f3c2a18b4e7",
  "grace_window_hours": 48,
  "secret_grace_until": "2026-06-07T10:42:11.183Z"
}
POST/v1/webhooks/{id}/rotate-secretGénère un nouveau secret de signature et conserve l'ancien valide pendant la fenêtre de grâce.

Cet endpoint génère un nouveau secret de signature pour le webhook identifié par {id} dans votre workspace. Le secret précédent reste valide pendant une fenêtre de grâce (par défaut 24 heures, jusqu'à 168 heures soit 7 jours), pendant laquelle Coffrify accepte les deux secrets pour signer les livraisons. Cela permet à votre récepteur de mettre à jour le secret stocké sans manquer aucun événement. Le nouveau secret suit le format whsec_ suivi de 64 caractères hexadécimaux (32 octets aléatoires). Le secret en clair n'est renvoyé qu'une seule fois, dans cette réponse : conservez-le immédiatement.

Authentification

Requiert une clé API valide disposant du scope webhooks:manage. Une clé sans ce scope reçoit une erreur scope_missing (403). Le webhook ciblé doit appartenir au workspace résolu par la clé : un {id} appartenant à un autre workspace renvoie not_found (404).

Corps de la requête

Le corps est facultatif. S'il est absent ou vide, la fenêtre de grâce par défaut de 24 heures s'applique.

ChampTypeRequisDescription
grace_window_hoursnumber (entier)NonDurée en heures pendant laquelle l'ancien secret reste valide. Doit être comprise entre 1 et 168 (7 jours). Les décimales sont tronquées vers le bas. Valeur par défaut : 24.

Réponse

Renvoie un statut 200 avec : webhook_id (l'identifiant du webhook), secret (le nouveau secret de signature en clair, à stocker immédiatement), rotated_at (horodatage ISO 8601 de la rotation), secret_grace_until (horodatage ISO 8601 jusqu'auquel l'ancien secret reste accepté) et grace_window_hours (la fenêtre de grâce effectivement appliquée, après troncature).

Erreurs

CodeQuandRésolution
validation_error (400)id absent dans l'URL, ou grace_window_hours hors de l'intervalle 1 à 168.Vérifiez le chemin et que grace_window_hours est un entier entre 1 et 168.
missing_api_key (401)En-tête Authorization absent.Ajoutez Authorization: Bearer cof_live_....
invalid_api_key (401)Clé API invalide ou mal formée.Utilisez une clé valide commençant par cof_live_ / cof_test_ (ou variantes restreintes/MCP).
scope_missing (403)La clé ne porte pas le scope webhooks:manage.Émettez une clé incluant le scope webhooks:manage.
not_found (404)Aucun webhook avec cet id dans le workspace de la clé.Vérifiez l'identifiant via la liste des webhooks.
rate_limited (429)Quota de requêtes du workspace dépassé.Patientez selon l'en-tête Retry-After, puis réessayez.
internal_error (500)Erreur de base de données lors de la lecture ou de la mise à jour du webhook.Réessayez ; si l'erreur persiste, contactez le support avec le request_id.

Voir aussi