Webhook

Le canal webhook générique est le fallback. Quand vous avez besoin de pousser des alertes vers une surface de chat, un système de ticketing ou un relais maison qu'Ongrid ne parle pas nativement (Microsoft Teams, Mattermost, Rocket Chat, OpsGenie, PagerDuty, votre propre routeur), pointez un webhook générique dessus et le pipeline d'alerte poste le JSON de message canonique d'Ongrid.

Utilisez le canal dédié quand il y en a un

Pour Slack / Feishu / DingTalk / WeCom / Telegram, les canaux dédiés rendent des payloads plus riches (attachments Slack, signature). Tendez la main vers le webhook générique seulement quand il n'y a pas de canal dédié.

Payload

Le corps est la forme canonique notify.Message, JSON-encodée verbatim :

{
  "severity": "critical",
  "subject": "node-01 swap_high",
  "body": "swap_in_pages > 1000 for 5m",
  "source": "alert",
  "labels": {
    "rule": "swap_high",
    "incident_id": "1234",
    "device_id": "7",
    "host": "node-01"
  },
  "dedupe_key": "alert:swap_high:device=7",
  "occurred_at": "2026-05-30T14:02:35Z"
}

Pas d'enveloppe, pas de msgtype, pas d'aplatissement. Le récepteur reçoit exactement les champs que le pipeline d'alerte a produits. Construit par NewGenericWebhookSender.

Signature HMAC optionnelle

Quand vous remplissez le champ Secret, chaque requête porte un en-tête X-Ongrid-Signature :

X-Ongrid-Signature: sha256=<hex>

Où <hex> est hex(HMAC-SHA256(secret, body)) sur les octets exacts postés. Le signer est signGenericWebhook.

Vérifier côté récepteur

# Python receiver
import hmac, hashlib

def verify(secret, body_bytes, header):
    expected = "sha256=" + hmac.new(
        secret.encode(), body_bytes, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)

// Go receiver
func verify(secret string, body, header []byte) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(body)
    expected := []byte("sha256=" + hex.EncodeToString(mac.Sum(nil)))
    return hmac.Equal(expected, header)
}

Vérifiez toujours la signature quand l'endpoint est public

Une URL de webhook générique sans signature est ouverte à quiconque apprend l'URL. L'en-tête de signature est la seule chose qui authentifie « ceci vient d'Ongrid ».

Forme de la requête

Propriété	Valeur
Méthode	POST
Content-Type	application/json
User-Agent	ongrid-notify/1.0
Corps	JSON de notify.Message
En-tête de sig	X-Ongrid-Signature: sha256=… (seulement si secret)
Timeout	Timeout http.Client par requête (défaut 15s)

Critère de succès

Le Sender traite HTTP 2xx (200–299) comme succès. Tout le reste — y compris les redirections 3xx, 4xx, 5xx — est unexpected status: … et compte comme une livraison échouée pour le pipeline de dampening. Le corps de la réponse n'est pas parsé ; Ongrid ne se soucie pas du JSON que votre relais renvoie.

Retry et dampening

La sémantique de retry est possédée par le pipeline d'alerte, pas par le Sender. Le Sender poste exactement une fois par appel Send(ctx, msg). Le pipeline décide :

• Fenêtre de dampening. Par règle, défaut 5 minutes. La même clé de dédoublonnage part au plus une fois par fenêtre.
• Repeat-on-still-firing. Défaut 1 heure. Si un incident est encore ouvert après cette fenêtre, le canal reçoit une re-notification pour qu'il ne se perde pas dans l'historique du chat.
• Message de récupération. Parti quand l'alerte se résout.

Le job du Sender est de pousser les octets. Le job du pipeline est de décider quand.

Pas de retry automatique sur échec de transport

Si le récepteur est down au moment où le Sender poste, le message est perdu (loggué comme erreur de livraison, présenté dans les stats de livraison par canal). Le pipeline n'enqueue pas et ne réessaye pas plus tard. Le raisonnement : une alerte de 5 minutes périmée livrée trois minutes après la récupération est plus déroutante qu'une manquante. Utilisez un récepteur robuste, ou intercalez votre propre file entre Ongrid et un aval instable.

Setup

1. Mettez en place un endpoint HTTP qui accepte POST + application/json. Choisissez un secret fort que vous partagerez avec Ongrid.
2. Dans Ongrid : Settings → Channels → New → Provider = webhook → Endpoint = votre URL → Secret = le secret partagé.
3. Cliquez sur Test. Le message test est le notify.Message{Severity: "info", Subject: "Ongrid test", …} synthétique. Vérifiez l'en-tête de signature dans les logs de votre récepteur.

Recettes

Microsoft Teams (webhook entrant)

Le webhook entrant Teams accepte une forme de payload différente (une MessageCard). Le chemin le plus simple est de mettre un petit adaptateur entre Ongrid et Teams :

# server.py - listens on /ongrid-to-teams
@app.post("/ongrid-to-teams")
def relay(msg: dict):
    teams_url = os.environ["TEAMS_WEBHOOK"]
    card = {
        "@type": "MessageCard",
        "@context": "https://schema.org/extensions",
        "themeColor": {"critical":"D92F2F","warning":"F2C037","info":"36A64F"}.get(msg["severity"], "6F7A87"),
        "title": msg["subject"],
        "text": msg["body"],
    }
    requests.post(teams_url, json=card)

Pointez le canal webhook Ongrid vers https://your-relay/ongrid-to-teams.

PagerDuty Events API v2

Même pattern : un petit relais qui traduit {severity, subject, body, dedupe_key} en payload PagerDuty events.v2. Le champ PD dedup_key mappe 1:1 au dedupe_key d'Ongrid, donc le même incident dans Ongrid est la même alerte dans PD.

Splunk HEC / Elastic ingest

Pointez le canal vers l'endpoint HEC avec le token Splunk dans l'URL. Splunk accepte le JSON canonique d'Ongrid ; indexez sur severity et labels.rule pour la recherche en aval.

Référence des champs

Voir Message pour la source de vérité. Champs stables :

Champ	Type	Notes
severity	string	critical / warning / info.
subject	string	Nom de règle + cible — une ligne.
body	string	Détail multi-ligne. Peut contenir des nouvelles lignes.
source	string	alert / test / etc.
labels	map[string]string	rule, incident_id, device_id, personnalisés.
dedupe_key	string	pipeline:rule:label-set. Stable par identité.
occurred_at	string RFC3339	UTC. Le moment où l'evaluator d'alerte est parti.

Les nouveaux champs sont additifs — les récepteurs devraient ignorer les clés inconnues.

Voir aussi

• Aperçu des canaux
• Schéma de règle d'alerte — pour ce que labels.rule signifie et comment les clés de dédoublonnage sont construites.