Guide d’intégration Webhook

Quand vous configurez un Webhook, Miharu envoie ses résultats de surveillance (alertes système) à l’URL de votre choix, sous forme de POST HTTP avec un corps JSON. Vous pouvez ainsi le relier à Zapier, Make, n8n, votre propre serveur et bien d’autres, pour traiter les notifications comme vous l’entendez.

Cette fonctionnalité s’adresse aux développeurs et aux utilisateurs avancés. Un point de terminaison de réception est nécessaire de votre côté.

1. Configuration

1. 1Dans l’app, ouvrez « Notifications externes » → « Webhook ».
2. 2Saisissez l’URL du Webhook de destination (elle doit commencer par https://).
3. 3Si besoin, définissez le filtre de notifications (par exemple, un seul groupe de surveillance).
4. 4À l’enregistrement, une notification de test confirmant la configuration est envoyée.

2. Spécification HTTP

Aucun en-tête de signature (HMAC ou autre) n’est envoyé. L’URL du Webhook est elle-même le secret (voir la section Sécurité).

3. Payload (champs communs)

4. Types d’événement et detail

Le diff de page_changed

diff est un tableau des modifications. Chaque élément est l’un des suivants :

• { "op": "added", "text": "..." }… une ligne ajoutée
• { "op": "removed", "text": "..." }… une ligne supprimée
• { "op": "replaced", "before": "...", "after": "..." }… une ligne remplacée

Si truncated vaut true, la différence était volumineuse et a été partiellement omise.

5. Exemples

{
  "source": "miharu",
  "version": "1",
  "id": "5c2e1b7a-9f3d-5a6b-8c4e-1d2f3a4b5c6d",
  "timestamp": "2026-05-22T01:23:45Z",
  "language": "fr",
  "event": "page_changed",
  "monitor": { "id": "abc123", "name": "Page produit", "url": "https://example.com/item" },
  "message": { "body": "La page a été mise à jour.", "label": "Mise à jour" },
  "detail": {
    "diff": [
      { "op": "replaced", "before": "Rupture de stock", "after": "En stock" },
      { "op": "added", "text": "Réassort effectué aujourd’hui" }
    ],
    "truncated": false
  }
}

{
  "source": "miharu", "version": "1", "id": "…",
  "timestamp": "2026-05-22T01:23:45Z", "language": "fr",
  "event": "keyword_hit",
  "monitor": { "id": "abc123", "name": "Page de disponibilité", "url": "https://example.com/stock" },
  "message": { "body": "Un mot-clé a été détecté.", "label": "Mot-clé" },
  "detail": { "hits": [ { "keywords": ["réassort"], "excerpts": ["…réassort effectué aujourd’hui…"] } ] }
}

{
  "…": "…",
  "event": "new_link",
  "message": { "body": "Un nouveau lien a été détecté.", "label": "Nouveau lien" },
  "detail": { "links": [ { "text": "Annonce d’un nouveau produit", "url": "https://example.com/news/123" } ] }
}

{
  "…": "…",
  "event": "price_changed",
  "message": { "body": "« Prix » a changé.\n\n1980 → 1480", "label": "Prix/Valeur" },
  "detail": { "target_name": "Prix", "before": "1980", "after": "1480" }
}

6. Idempotence (déduplication)

Un même événement arrive toujours avec le même id, y compris lors des réémissions (la même valeur figure aussi dans l’en-tête X-Miharu-Notification-Id). Utilisez id de votre côté pour éviter de traiter deux fois la même notification.

7. Sécurité

• HTTPS obligatoire (seules les URL en https:// peuvent être enregistrées).
• Aucun en-tête de signature n’est envoyé : traitez donc l’URL du Webhook elle-même comme un secret (si elle fuite, un tiers pourrait envoyer de fausses notifications).
• Au besoin, incluez un jeton aléatoire dans l’URL (par exemple https://example.com/hook/<aléatoire>) et vérifiez-le de votre côté.
• Pour une identification sommaire de l’émetteur, vous pouvez vous appuyer sur User-Agent: Miharu-Webhook/1.0 et sur les en-têtes X-Miharu-* (à titre indicatif seulement).

8. Intégrations

Générez une URL de réception dans votre service et enregistrez-la comme URL de Webhook dans Miharu.

• Zapier : l’URL de « Webhooks by Zapier » → « Catch Hook »
• Make : l’URL d’un « Custom webhook »
• n8n : l’URL d’un nœud « Webhook »
• Votre propre serveur : un point de terminaison qui accepte le corps JSON et renvoie 2xx

9. Limites

• Le Webhook transmet les alertes système (les détections) et les notifications système.
• Les différences ou les textes longs peuvent être tronqués (par exemple truncated: true).
• Le filtre de notifications permet de limiter l’envoi à un groupe de surveillance donné.

10. Résolution des problèmes

• L’URL commence-t-elle par https:// ?
• Votre point de terminaison renvoie-t-il 2xx ? (Les redirections et les erreurs comptent comme des échecs.)
• L’envoi s’est-il arrêté après des réponses répétées autres que 2xx ? Vérifiez l’état dans l’app et reconfigurez le Webhook pour reprendre.
• Le traitement dépasse-t-il 10 secondes (délai d’attente) ? Renvoyez 2xx immédiatement et traitez en asynchrone.

Pour toute remarque ou suggestion, écrivez-nous depuis « Avis et suggestions » dans l’app.