Webhooks Moon AI : notifications temps réel pour vos apps

Quand votre application interagit avec l'IA, vous avez parfois besoin d'être notifié en temps réel : une génération longue qui se termine, un quota qui approche de sa limite, une donnée sensible détectée par Moon Guard. C'est exactement ce que permettent les webhooks Moon AI.

Qu'est-ce qu'un webhook ?

Un webhook est un appel HTTP que Moon AI envoie vers votre serveur quand un événement se produit. Au lieu de poller l'API toutes les secondes pour vérifier si quelque chose a changé, vous recevez une notification push instantanée.

Configuration

Dans votre dashboard Moon AI, rendez-vous dans Paramètres → Webhooks et ajoutez une URL de destination :

https://votre-app.com/api/webhooks/moon-ai

Sélectionnez les événements qui vous intéressent et Moon AI génère une clé de signature (whsec_...) pour vérifier l'authenticité des appels.

Événements disponibles

• chat.completion.created — Une réponse IA a été générée (utile pour les traitements asynchrones)
• guard.detection — Moon Guard a détecté et anonymisé des données sensibles
• document.generated — Un document (PDF, DOCX) a été généré avec succès
• workflow.completed — Un workflow automatisé a terminé son exécution
• workflow.failed — Un workflow a échoué (avec détails de l'erreur)
• quota.warning — Vous approchez de votre limite de quota (80%)
• quota.exceeded — Quota dépassé

Format du payload

Chaque webhook envoie un JSON structuré :

{
  "id": "evt_1a2b3c4d",
  "type": "chat.completion.created",
  "created_at": "2026-04-09T14:30:00Z",
  "data": {
    "completion_id": "cmpl_x7y8z9",
    "model": "claude-sonnet",
    "tokens_used": 1247,
    "duration_ms": 3200,
    "guard_applied": true,
    "guard_detections": ["email", "phone"]
  }
}

Vérification de la signature

Chaque requête webhook inclut un header X-Moon-Signature. Vérifiez-le pour vous assurer que l'appel vient bien de Moon AI :

Node.js

import crypto from "crypto";

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Dans votre route Express
app.post("/api/webhooks/moon-ai", (req, res) => {
  const sig = req.headers["x-moon-signature"];
  if (!verifyWebhook(JSON.stringify(req.body), sig, WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }

  const { type, data } = req.body;

  switch (type) {
    case "guard.detection":
      console.log("Moon Guard a détecté :", data.guard_detections);
      break;
    case "quota.warning":
      notifyTeam("Quota Moon AI à 80%");
      break;
  }

  res.status(200).send("OK");
});

Python

import hmac, hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

# Dans votre route Flask
@app.route("/api/webhooks/moon-ai", methods=["POST"])
def handle_webhook():
    sig = request.headers.get("X-Moon-Signature")
    if not verify_webhook(request.data, sig, WEBHOOK_SECRET):
        return "Invalid signature", 401

    event = request.json
    if event["type"] == "workflow.failed":
        alert_ops_team(event["data"])

    return "OK", 200

Bonnes pratiques

• Répondez vite — Renvoyez un 200 immédiatement, puis traitez l'événement en arrière-plan. Moon AI attend 5 secondes max avant de considérer l'appel comme échoué.
• Gérez les doublons — Utilisez le champ id pour dédupliquer. Moon AI peut renvoyer un événement en cas de timeout.
• Retry automatique — En cas d'échec (5xx ou timeout), Moon AI retente 3 fois avec un backoff exponentiel (1min, 5min, 30min).
• Filtrez les événements — Ne vous abonnez qu'aux événements utiles pour éviter le bruit.
• Loggez tout — Conservez les payloads reçus pour le debug et l'audit.

Les webhooks transforment Moon AI d'un simple outil de chat en une brique d'infrastructure intégrée dans votre stack technique. Configurez-les une fois, et votre application réagit en temps réel à tout ce qui se passe côté IA.