Webhooks

Un webhook est le canal pour ceux qui veulent relier une alerte à leurs propres outils : un script, un tableau de statut, un système d’astreinte, un petit service qui ouvre un ticket. Quand un site web tombe, et quand il revient, UptimeWire envoie une requête HTTP à l’adresse que vous avez définie.

Ce que transporte un webhook

Les avertissements sur le certificat, le domaine et le DNS ne sont pas envoyés par webhook. Ils vous parviennent par e-mail et, si vous l’avez connecté, par Telegram.

Le configurer

Vous définissez l’adresse dans votre compte UptimeWire, dans les paramètres de notification de votre profil. Seul le titulaire du compte peut l’ajouter, la modifier, la tester ou la supprimer.

1. Saisissez l’adresse de votre récepteur. Elle doit commencer par https://.
2. Appuyez sur « Enregistrer l’adresse ». Un secret de signature est créé la première fois que vous enregistrez.
3. Copiez le secret de signature dans votre récepteur. Il commence par whsec_.
4. Appuyez sur « Envoyer un message de test ». Le résultat s’affiche immédiatement.

L’adresse est la même pour tous les sites web du compte. Vous ne pouvez pas choisir une adresse différente pour un site web.

Quelles adresses sont acceptées

UptimeWire refuse une adresse qui :

• n’utilise pas https://, ou qui contient un nom d’utilisateur ou un mot de passe ;
• pointe vers un réseau privé ou interne, vers la machine elle-même, ou vers une astuce numérique comme une adresse IP décimale ou hexadécimale ;
• dépasse 2 048 caractères.

L’adresse est vérifiée quand vous l’enregistrez, puis de nouveau avant l’envoi de chaque message.

Le message

La requête est un POST HTTP avec un corps JSON. Cet exemple est donné à titre d’illustration : les valeurs sont inventées.

{
  "id": "4182",
  "event": "incident.opened",
  "site": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "Shop",
    "url": "https://shop.example.com"
  },
  "incident": {
    "id": "00000000-0000-0000-0000-000000000001",
    "started_at": "2026-11-01T10:15:00Z",
    "ended_at": null,
    "duration_seconds": null,
    "cause": "HTTP 503"
  }
}

Pour incident.closed, le corps a la même forme, avec ended_at et duration_seconds renseignés. Pour test, site et incident valent null. Les heures sont en UTC.

L’id identifie l’envoi, pas l’incident. La partie incident montre son état au moment de l’envoi du message : un incident.opened tardif peut donc déjà porter un ended_at. Ignorez les champs que vous ne connaissez pas, pour que votre récepteur continue de fonctionner si un champ est ajouté.

En-têtes

Vérifier la signature

Toute personne qui apprend votre adresse peut lui envoyer une requête. La signature permet à votre récepteur de distinguer un vrai message UptimeWire d’un message falsifié.

La signature est un HMAC avec SHA-256, écrit en hexadécimal. Elle est calculée avec votre secret de signature sur le texte composé de l’heure t, d’un point et du corps brut.

Pour vérifier un message :

1. Lisez le corps brut avant de l’analyser comme du JSON. L’analyser puis le réécrire peut le modifier.
2. Lisez t et v1 dans l’en-tête X-UptimeWire-Signature.
3. Calculez le HMAC de t, d’un point et du corps brut, avec votre secret de signature.
4. Comparez votre résultat à v1 avec une comparaison à temps constant.
5. Rejetez le message si t s’écarte de plus de cinq minutes de votre propre horloge.

Si vous créez un nouveau secret dans votre compte, l’ancien cesse de fonctionner immédiatement. Il n’y a pas de période de chevauchement.

Envoi et nouvelles tentatives

Un envoi est considéré comme réussi quand votre récepteur répond avec un statut 2xx en moins de cinq secondes. Tout le reste est un échec : un autre statut, un dépassement de délai, un problème de certificat ou une connexion refusée. UptimeWire ne suit pas les redirections, et une réponse 3xx est un échec.

Un message en échec est tenté jusqu’à cinq fois au total : tout de suite, puis après 1, 5, 30 et 120 minutes. Après la dernière tentative, il est marqué comme échoué. UptimeWire ne vous envoie pas d’e-mail à ce sujet, mais le tableau de bord montre qu’une alerte n’a pas été livrée. Il ne désactive pas l’adresse.

Dans de rares cas, le même message peut arriver deux fois, et les messages peuvent arriver dans le désordre. Conservez l’id de chaque message que vous traitez, et utilisez started_at pour décider quel état est le plus récent.

Ce que vous voyez dans votre compte

La carte du webhook dans votre compte comporte un journal d’envoi avec les 20 derniers messages. Pour chacun, elle affiche le site web, le type de message, le statut (livré, échoué, nouvelle tentative prévue, en attente ou annulé), le nombre de tentatives et le résultat, par exemple « Réponse 200 ».

Limites

• Une seule adresse par compte, partagée par tous les sites web. Seul le titulaire du compte peut la modifier.
• Pannes et rétablissements uniquement.
• Inclus à partir de l’offre Starter. Si un compte passe à une offre sans webhooks, les messages en attente sont annulés et aucun nouveau n’est créé. L’adresse et le secret sont conservés, et les messages reprennent après un changement d’offre vers le haut.
• Les messages sont envoyés au moins une fois, pas exactement une fois.
• UptimeWire ne lit pas la réponse que renvoie votre récepteur.

Dépannage

• « Cette adresse n’est pas autorisée. » L’adresse mène à un réseau privé ou interne. Utilisez une adresse publique.
• « L’adresse doit commencer par https://. » Le simple http:// n’est pas accepté.
• « L’adresse n’a pas répondu en 5 secondes. » Répondez d’abord et faites le travail lent ensuite, par exemple en plaçant le message dans une file d’attente.
• « Réponse 3xx : les redirections ne sont pas suivies. » Définissez l’adresse finale.
• Les messages arrivent mais la signature ne correspond pas. Vérifiez que vous la calculez sur le corps brut et que vous utilisez le secret actuel.
• « Trop de messages de test. » Le bouton de test est limité à cinq par minute.

Telegram, Discord, Slack et Microsoft Teams sont des canaux distincts. Consultez la vue d’ensemble des intégrations pour voir ce que chacun transporte.