Webhooks

Présentation

Un webhook générique envoie une requête HTTP POST vers n’importe quel endpoint lorsque l’état d’un monitor change. C’est le moyen le plus flexible d’intégrer OKStatus à un outil qui n’a pas de canal dédié — et c’est disponible sur tous les plans, Free compris.

Configuration

1. Allez dans Alerting → Canaux → Ajouter un canal → Webhook.
2. Renseignez l’URL de destination.
3. Définissez éventuellement un secret — il vous est renvoyé à chaque appel, ce qui vous permet de rejeter les requêtes qui ne le portent pas.
4. Cliquez sur Tester, puis rattachez le canal à vos monitors.

L’URL doit être résolvable publiquement : une adresse qui résout vers une IP privée ou réservée est refusée, à l’enregistrement du canal comme au moment de l’envoi.

Payload

{
  "event": "monitor.down",
  "monitor": {
    "name": "Site web principal",
    "url": "https://example.com"
  },
  "region": "fr-dc3",
  "timestamp": "2026-09-09T14:30:00.000Z"
}

Le payload est volontairement petit et stable. Tout le reste — code HTTP, latence, uptime — est à un appel authentifié de l’API REST, via le nom ou l’URL du monitor.

Événements disponibles

event	Envoyé quand
monitor.down	Le monitor est confirmé down
monitor.degraded	Panne partielle, réponse lente, ou écart sur une redirection
monitor.up	Le monitor est rétabli
monitor.paused	Le monitor a été mis en pause
slo.budget	Un SLO consomme vite son budget, passe 75 % ou est épuisé

Un monitor.degraded envoyé par une alerte de temps de réponse porte quatre champs de plus, pour qu’un récepteur traite la lenteur à part des pannes : "reason": "latency_threshold", latencyMs (le temps mesuré), thresholdMs (le seuil du monitor) et slowRegions (les codes des régions lentes). Tous les autres événements gardent le payload ci-dessus, inchangé.

Une alerte de latence anormale (Max et Enterprise) porte "reason": "latency_anomaly" à la place, avec latencyMs (le p95 des 15 dernières minutes), usualMs ({ "low": …, "high": … }, la plage habituelle à cette heure) et slowRegions.

Un événement slo.budget (Max et Enterprise) porte kind (fast_burn, 75_percent ou exhausted), subject (type monitor ou group, id, name), target, windowDays (30), budgetMinutes, consumedMinutes, remainingMinutes, exhaustsAt et, pour fast_burn, burn (windowMinutes, burnedMinutes).

Il n’existe pas d’événement incident.* : les incidents sont ce que vous rédigez, pas ce que le moteur détecte. Lisez-les ou créez-les via l’API Incidents.

Sécurité

Si vous définissez un secret sur le canal, chaque requête le transporte tel quel dans un header X-Webhook-Secret. Comparez-le à votre propre copie et rejetez la requête si elle ne correspond pas.

Attention

Il s’agit d’un secret partagé, pas d’une signature HMAC du corps — il n’y a pas de header X-OKStatus-Signature à vérifier. Traitez le secret comme un mot de passe : uniquement en HTTPS, et faites-le tourner en éditant le canal.

Une réponse non-2xx marque la notification comme échouée sur l’alerte, visible par une ✗ à côté du canal dans le Journal des alertes. OKStatus ne réessaie pas l’appel.