Webhooks

Les webhooks vous envoient les événements à l'instant où ils se produisent, au lieu que vous interrogiez l'API REST. Enregistrez un endpoint HTTPS : CrunchJunkie y enverra en POST une charge utile JSON signée chaque fois qu'un événement auquel vous êtes abonné se déclenche. Vous pouvez ainsi lever une alerte Slack lors d'une baisse de visibilité, lancer un workflow à la fin d'un scan ou répliquer les événements dans votre propre base de données, sans cron de votre côté. Chaque livraison est signée (vous pouvez donc prouver qu'elle vient de nous), renvoyée automatiquement si votre endpoint est brièvement indisponible, et consignée. Les webhooks sont disponibles avec les forfaits Pro, Agency et Scale, et seul un propriétaire ou un administrateur de l'espace de travail peut les gérer. Si l'espace de travail n'a plus de forfait Pro, Agency ou Scale actif, rien n'est envoyé (chaque livraison est consignée comme ignorée), et un propriétaire ou un administrateur peut toujours désactiver ou supprimer les endpoints.

Ouvrez Paramètres → Webhooks et ajoutez l'URL HTTPS de votre récepteur (http:// est refusé). Choisissez les événements qu'il doit recevoir, tous ou une sélection, et, si vous le souhaitez, une description. À l'enregistrement, nous affichons le secret de signature une seule fois. Il ressemble à whsec_… : copiez-le tout de suite dans votre récepteur, nous ne pourrons pas le réafficher, seulement le renouveler. Utilisez le bouton « Envoyer un test » pour envoyer un événement d'exemple à votre endpoint et vérifier qu'il accepte et valide la livraison avant de vous y fier.

Nous envoyons en POST une enveloppe JSON au format Standard Webhooks : { "id": "msg_…", "type": "signal.created", "timestamp": "2026-08-28T10:00:00.000Z", "api_version": "2026-08-01", "data": { … } } • id : un identifiant de message unique, également envoyé dans l'en-tête webhook-id. Utilisez-le comme clé d'idempotence pour qu'une nouvelle tentative ne soit jamais traitée deux fois. • type : le type d'événement (voir ci-dessous). • data : l'objet complet de l'événement, si bien que vous avez rarement besoin d'un appel d'API supplémentaire. Renvoyez n'importe quel statut 2xx pour accuser réception. Tout autre statut (ou un délai dépassant 15 secondes) est considéré comme un échec et donne lieu à une nouvelle tentative.

Trois en-têtes accompagnent chaque livraison : webhook-id, webhook-timestamp (secondes Unix) et webhook-signature. La signature est un HMAC-SHA256 calculé sur la chaîne `{id}.{timestamp}.{body}`, encodé en base64 et précédé de v1,. C'est le schéma Standard Webhooks : toute bibliothèque compatible svix la vérifie, ou vous pouvez la vérifier à la main : import crypto from "node:crypto"; function verify(secret, headers, body) { const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64"); const signed = `${headers["webhook-id"]}.${headers["webhook-timestamp"]}.${body}`; const expected = "v1," + crypto.createHmac("sha256", key).update(signed).digest("base64"); return headers["webhook-signature"].split(" ").some(s => crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected))); } Vérifiez toujours la signature sur le corps BRUT de la requête (avant l'analyse du JSON) et rejetez les livraisons dont le webhook-timestamp date de plus de cinq minutes, pour empêcher les rejeux.

Types d'événements actuels : • signal.created : un nouveau signal a été détecté (baisse de visibilité, dépassement par un concurrent, baisse du score GEO, source morte, signal inter-canaux, compte publicitaire Meta qui a cessé de diffuser). Seuls les signaux réellement nouveaux se déclenchent : un constat toujours vrai ne vous inonde pas. La charge utile contient n avec nUnit (ce qu'il compte) et une confiance uniquement lorsqu'un test en a calculé une (confidenceKind tested ; null pour un fait compté). title et detail sont les mots anglais enregistrés avec le signal, conservés tels quels ; text ({ lang, title, detail }) ajoute les mêmes mots dans la langue de l'espace de travail, rédigés à partir des éléments du signal. L'action webhook d'une automatisation envoie le même text à côté de title et detail. • scan.completed : un scan de visibilité IA s'est terminé, et data.status indique comment : done (toutes les vérifications sont enregistrées), error (il s'est terminé avec des vérifications définitivement en échec) ou stopped (quelqu'un l'a arrêté, avec le bouton Arrêter ou en supprimant son client, ou le budget Managed AI l'a mis en pause). Un scan qu'un autre poursuit n'envoie pas d'événement de son côté : le scan qui l'a remplacé (un Lancer le scan fait par une personne qui remplace le premier scan automatique ou un scan qui n'avait pas démarré) ou qui a pris le relais (un scan en file d'attente qui reprend un scan piloté qui n'a abouti à rien) en envoie un à sa fin, avec les identifiants de tous les scans qu'il a poursuivis dans data.replaced. Aucun événement n'est envoyé pour un scan en file d'attente annulé avant de démarrer (il n'a jamais tourné), pour un scan que la vérification des scans bloqués termine (aucune progression depuis des heures, ou vieux d'une semaine), ni pour un scan que la planification remplace après qu'il a tourné 6 heures sans se terminer. Si une livraison échoue, nous réessayons avec un délai exponentiel : après 5 s, puis 5 min, 30 min, 2 h, 5 h et 10 h, jusqu'à huit tentatives réparties sur plus d'une journée ; le même webhook-id est réutilisé à chaque nouvelle tentative. Après de nombreux échecs consécutifs, un endpoint est désactivé automatiquement (le motif s'affiche dans Paramètres), de sorte qu'une URL définitivement morte cesse de générer du trafic ; réactivez-le une fois le problème corrigé. Les événements encore en file pour un endpoint au moment de sa désactivation sont clos comme ignorés et ne sont pas renvoyés après la réactivation. Vous pouvez renouveler le secret de signature à tout moment depuis le même écran : l'ancien secret cesse de fonctionner immédiatement, mettez donc votre récepteur à jour en même temps.