📡 Intégration Uptime Kuma

Ouvrez automatiquement un Incident de service dans Microscope dès que Uptime Kuma détecte qu'un service surveillé est hors ligne, grâce à une notification Webhook authentifiée par une clé d'API Microscope.

Principe de fonctionnement

Lorsqu'une sonde tombe en panne, Uptime Kuma envoie une requête HTTP POST à l'endpoint d'incidents de Microscope avec un corps JSON personnalisé. Microscope authentifie l'appel à l'aide d'une clé d'API (transmise dans un en-tête), en déduit le tenant de l'appelant, puis crée un nouvel incident de service rattaché au workload référencé.

Uptime Kuma  ──POST /api/v1/tech/incidents (X-API-KEY)──▶  API Microscope  ──▶  Incident de service

Prérequis

• Une clé d'API Microscope provisionnée pour votre tenant (demandez à votre administrateur). La clé porte le tenant et le rôle utilisés pour autoriser l'appel.
• L'identifiant du Workload auquel rattacher l'incident (copiez-le depuis la page du workload).
• L'URL de base de l'API Microscope, par ex. https://votre-hote-microscope.

1. Créer la notification Webhook dans Uptime Kuma

Dans Uptime Kuma, allez dans Paramètres → Notifications → Configurer une notification et choisissez Webhook.

Champ	Valeur
Type de notification	Webhook
Post URL	https://votre-hote-microscope/api/v1/tech/incidents
Corps de la requête	Custom Body

Corps personnalisé (Custom Body)

Collez le JSON suivant comme corps personnalisé. Il utilise le moteur de templates Liquid, qu'Uptime Kuma interprète avant l'envoi :

{
  "workloadId": "ef112e43-bc11-45c5-8c20-2515571fec39",
  "label": "{{ name }} availability incident",
  "incidentSeverity": 1
}

• workloadId — le workload Microscope auquel l'incident est rattaché. Remplacez par votre propre identifiant.
• label — {{ name }} est la variable Liquid correspondant au nom de la sonde ; une sonde nommée Web application produit donc le libellé Web application availability incident.
• incidentSeverity — la sévérité de l'incident (voir le tableau ci-dessous).

💡 Le champ startDate est optionnel. Si vous l'omettez (comme ci-dessus), Microscope le renseigne avec l'heure de réception du webhook. Pour utiliser l'heure de détection exacte d'Uptime Kuma, ajoutez : "startDate": "{{ heartbeatJSON.time | replace: ' ', 'T' | append: 'Z' }}". Notez que heartbeatJSON n'est disponible que sur les vrais événements UP/DOWN, pas via le bouton Test.

Valeurs de sévérité

Valeur	Sévérité
0	Faible
1	Moyenne
2	Élevée
3	Critique

En-têtes additionnels (Additional Headers)

Uptime Kuma ne dispose pas de champ dédié à la clé d'API : la clé — ainsi que le type de contenu — sont donc transmis via les Additional Headers :

{
  "X-API-KEY": "dev-sample-key-002",
  "Content-Type": "application/json"
}

• X-API-KEY — votre clé d'API Microscope. Microscope la lit dans cet en-tête, identifie le tenant et autorise la requête.
• Content-Type: application/json — obligatoire. L'endpoint n'accepte que du JSON ; sans cet en-tête, la requête est rejetée avec une erreur HTTP 415 (Unsupported Media Type).

2. Associer la notification à vos sondes

Créer la notification ne suffit pas. Ouvrez chaque sonde à surveiller et, dans la section Notifications, activez la notification Webhook.

⚠️ Le bouton Test fonctionne sans cette étape, mais les vrais événements « hors ligne » ne déclenchent le webhook que pour les sondes où la notification est activée.

Dépannage

Symptôme	Cause / Solution
HTTP 415	L'en-tête Content-Type: application/json est absent des Additional Headers.
HTTP 401	La clé X-API-KEY est absente ou invalide.
HTTP 403	Le rôle de la clé n'est pas autorisé à créer des incidents.
Le Test crée un incident dont le libellé est Monitor Name not available …	Comportement normal — lors d'un Test il n'y a pas de sonde, donc {{ name }} renvoie une valeur par défaut. Les vrais événements utilisent le nom réel de la sonde.
La sonde est hors ligne mais aucun incident n'est créé	La notification n'est pas activée sur la sonde, ou son compteur de tentatives (Retries) n'est pas encore épuisé. Vérifiez les réglages Notifications et Retries de la sonde.

ℹ️ Chaque événement « hors ligne » crée un nouvel incident ; Uptime Kuma ne déduplique pas. Si un service reste hors ligne sur plusieurs battements, vous pouvez recevoir plusieurs incidents.