Aller au contenu
CodeCleared Docs
ApplicationEnglish
Publié

Dernière revue: 2026-09-11

Webhooks sortants

Livrez de façon sécurisée les événements de scan, politique, score et constats CodeCleared vers votre récepteur HTTPS, avec signatures, retries et idempotence.

Objectif

Les webhooks livrent les événements de scan, politique, score, contrôles de PR et cycle de vie des constats vers votre récepteur HTTPS. Configurez les endpoints dans Paramètres → Webhooks et stockez chaque secret d’endpoint dans un gestionnaire de secrets dédié.

Prérequis

Les webhooks sont généralement disponibles à partir du plan Team. Votre récepteur doit accepter HTTPS, conserver le corps brut de la requête, répondre rapidement avec succès, et pouvoir dédupliquer les livraisons.

Étapes

  1. Ajoutez un endpoint HTTPS et sélectionnez uniquement les événements dont votre process a besoin.
  2. Conservez le secret d’endpoint hors du code source.
  3. Envoyez une livraison de test et inspectez vos logs sans retenir de secrets de payload.
  4. Vérifiez la signature avant de parser ou d’agir sur l’événement.
import crypto from 'node:crypto';

export function verifyWebhook(rawBody, signature, secret, now = Math.floor(Date.now() / 1000)) {
  const fields = Object.fromEntries(signature.split(',').map(part => part.split('=')));
  const timestamp = Number(fields.t);
  if (!Number.isFinite(timestamp) || Math.abs(now - timestamp) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
  return fields.v1 && crypto.timingSafeEqual(Buffer.from(fields.v1), Buffer.from(expected));
}

Règles métier

En-têtes : X-CodeCleared-Event, X-CodeCleared-Delivery, X-CodeCleared-Signature. La signature est t=unix,v1=hex : HMAC-SHA256 sur ${t}.${rawBody}. Rejetez les horodatages hors d’environ 300 secondes et utilisez l’ID de livraison comme clé d’idempotence. Les événements visibles incluent scan.completed, compliance_score.changed, violations de politique / PR check, et le cycle de vie SLA / gouvernance.

Scénarios et cas limites

Livraison en double : accuserez réception après contrôle d’idempotence. Signature incorrecte : utilisez le corps brut intact et le bon secret. Livraison trop ancienne : rejetez-la. Migration d’endpoint : ajoutez et testez le nouveau avant de retirer l’ancien.

Limites

Une organisation peut configurer environ 10 endpoints et consulter environ 100 entrées d’historique de livraison. Ce sont des limites produit ; n’utilisez pas l’URL d’endpoint pour des credentials. Pour créer des tickets Jira/Linear sans construire de récepteur, voir Suivi des tickets.

Erreurs courantes

  • Parser puis resérialiser le corps avant vérification.
  • Comparer les signatures avec une égalité de chaînes classique.
  • Ignorer X-CodeCleared-Delivery et créer des tickets en double.
  • Traiter un échec de livraison comme une permission de sauter la vérification.

Liens