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

Allez dans Alerting → Canaux → Ajouter un canal → Webhook.
Renseignez l’URL de destination.
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.
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

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.

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.