Webhooks

Les webhooks Abyss Monitor notifient une URL externe à chaque fois qu'un événement applicatif ou un check de Sentinel se produit. C'est la façon recommandée pour brancher Monitor à un système externe (Slack, dispatcher d'alertes, automatisation interne, etc.).

Portées (scopes)

Un webhook déclare un ou plusieurs scopes :

EVENT

Déclenché quand un événement applicatif est reçu. Vous pouvez filtrer les événements écoutés par :

• equals — match exact (ex. auth.user.signup),
• startsWith — préfixe (ex. auth.),
• endsWith — suffixe (ex. .error),
• include — sous-chaîne.

Les filtres sont cumulatifs : un événement passe s'il valide au moins une règle.

SENTINEL

Déclenché à chaque check d'un Sentinel. Filtres disponibles :

• type — restreindre à un ou plusieurs types (PING, HTTP, TCP),
• notifyOnSuccess — notifier sur succès,
• notifyOnFailure — notifier sur échec.

Créer un webhook

1. Ouvrez l'Application dans Abyss Monitor et allez sur l'onglet Webhooks.
2. Cliquez sur Créer.
3. Renseignez :
   • Nom et description pour vous y retrouver,
   • URL cible (HTTPS recommandé),
   • Scopes (EVENT, SENTINEL, ou les deux) et leurs filtres,
   • L'état Activé / désactivé.
4. Validez. Un secret de signature est généré : conservez-le, il sert à valider les payloads côté serveur.

Signature et validation

Chaque appel sortant inclut une signature HMAC SHA-256 du corps, calculée avec le secret du webhook. L'en-tête est abyss-monitor-webhook-signature.

Côté receveur, recalculez la même signature à partir du corps brut et du secret, puis comparez :

import crypto from 'crypto';

const signature = req.headers['abyss-monitor-webhook-signature'];
const expected = crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(JSON.stringify(req.body))
  .digest('hex');

if (signature !== expected) {
  throw new Error('Invalid signature');
}

Si vous pensez que le secret est compromis, vous pouvez le régénérer depuis la page du webhook. L'ancien secret est immédiatement invalidé.

Historique des deliveries

Chaque déclenchement crée une entrée dans l'historique du webhook. L'historique conserve :

• l'événement ou le check qui a déclenché l'envoi,
• le code de réponse HTTP renvoyé par votre serveur,
• la durée de l'appel,
• le corps envoyé et la réponse reçue.

Retry et erreurs

Si votre serveur renvoie une erreur (5xx, timeout), Abyss Monitor réessaie automatiquement avec un délai croissant entre chaque tentative. Une fois le nombre de tentatives épuisé, la delivery est marquée en échec et reste consultable dans l'historique.

Pour ne rater aucun événement, répondez avec un code 2xx dès que vous avez reçu et persisté la donnée. Le traitement métier peut être asynchrone côté receveur.

Gérer les webhooks existants

Depuis l'onglet Webhooks, vous pouvez :

• éditer un webhook (URL, filtres, statut activé / désactivé),
• consulter l'historique des deliveries,
• régénérer le secret de signature,
• supprimer un webhook.