Webhooks

Recevez une requête HTTPS signée sur votre propre URL quand quelque chose se passe sur votre site.

Configurer un point de terminaison

Ouvrez les Paramètres du site, onglet Données, section Webhooks. Ajoutez l'URL, choisissez les déclencheurs et copiez le secret de signature. Il n'est affiché qu'une fois ; vous pourrez le renouveler. Les webhooks sont disponibles à partir du plan Starter. Chaque site peut avoir jusqu'à 10 points de terminaison, et un point de terminaison appartient à un seul site.

Déclencheurs

  • event.received : un événement personnalisé que vous avez nommé (20 noms maximum par point de terminaison). Une requête par événement.
  • goal.converted : un objectif a été atteint, une fois par session et par objectif. Inclut la source de trafic de la visite. Choisissez tous les objectifs ou certains.
  • alert.triggered : l'une de vos alertes de trafic s'est déclenchée.
  • uptime.down et uptime.up : votre site a cessé ou repris de répondre.

Les événements et objectifs sont relevés environ une fois par minute : comptez 30 à 90 secondes de délai.

Contenu

Les points de terminaison JSON reçoivent un corps au format Standard Webhooks. Le champ text est un résumé d'une ligne, en anglais.

{
  "id": "whd_1234",
  "type": "goal.converted",
  "created_at": "2026-10-27T10:15:00Z",
  "site": { "id": "5b1f0c2e-...", "domain": "example.com" },
  "data": {
    "goal": { "id": "...", "name": "Signup", "type": "pageview", "target": "/thanks" },
    "pathname": "/thanks",
    "occurred_at": "2026-10-27T10:14:41.000Z",
    "source": {
      "channel": "Organic Search",
      "referrer_domain": "google.com",
      "utm_source": null,
      "utm_medium": null,
      "utm_campaign": null
    }
  },
  "text": "Goal \"Signup\" converted on example.com (from Organic Search)."
}

Le contenu ne comporte jamais d'identifiant de visiteur ou de session, d'adresse IP ni de ville. Les propriétés d'événement sont celles que vous avez envoyées. Le contenu est limité à 64 Ko ; si les propriétés ne tiennent pas, elles sont omises et truncated vaut true.

Slack et Discord

Choisissez le format Slack ou Discord pour publier le résumé texte sur une URL de webhook entrant, au lieu de l'enveloppe JSON.

En-têtes et signature

  • webhook-id : l'identifiant de l'envoi. Il reste identique d'une tentative à l'autre, ce qui permet d'ignorer les doublons.
  • webhook-timestamp : secondes unix de cette tentative.
  • webhook-signature : v1, suivi du HMAC-SHA256 en base64 de id.timestamp.body, avec votre secret comme clé (décodé en base64, sans le préfixe whsec_).

Vérifier une requête

Toute bibliothèque Standard Webhooks convient. En Node.js, sans bibliothèque :

import { createHmac, timingSafeEqual } from "node:crypto";

// secret: the whsec_... value shown once when you created the endpoint
// rawBody: the request body exactly as received (a string, not parsed JSON)
export function verify(secret, headers, rawBody) {
  const id = headers["webhook-id"];
  const ts = headers["webhook-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // replay window

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${ts}.${rawBody}`).digest("base64");

  return headers["webhook-signature"].split(" ").some((part) => {
    const [version, sig] = part.split(",");
    if (version !== "v1") return false;
    const a = Buffer.from(sig);
    const b = Buffer.from(expected);
    return a.length === b.length && timingSafeEqual(a, b);
  });
}

Nouvelles tentatives et désactivation

Répondez par un statut 2xx en moins de 10 secondes. Toute autre réponse est un échec, retenté après 1 minute, 5 minutes, 30 minutes, 2 heures et 8 heures, soit environ 11 heures au total. Les redirections ne sont pas suivies.

Une réponse 410 désactive le point de terminaison immédiatement. Après 25 échecs consécutifs sans succès en 24 heures, il est désactivé et le propriétaire du site reçoit un e-mail. Réactivez-le dans les paramètres quand l'URL fonctionne de nouveau. Ouvrez Envois sur un point de terminaison pour voir les 50 dernières tentatives et relancer celles qui ont échoué.

Limites

  • Événements personnalisés : 500 envois par heure au maximum par point de terminaison. Les événements au-delà sont comptés dans les paramètres mais pas envoyés.
  • URL https publiques uniquement. Les adresses de réseaux privés sont bloquées.
  • Les événements d'un site sous-domaine vont aux points de terminaison de ce site sous-domaine.

Auto-hébergement

Définissez WEBHOOKS_ALLOW_PRIVATE=1 pour autoriser les points de terminaison sur votre réseau et le http simple. Voir le guide d'auto-hébergement.