> ## Documentation Index > Fetch the complete documentation index at: https://docs.querying.ai/llms.txt > Use this file to discover all available pages before exploring further. # Événements et alertes de moniteur : webhooks et notifications par e-mail > Recevez un webhook signé quand les réponses d'un moniteur changent, et un e-mail quand votre taux de mention passe sous un seuil. Un moniteur peut vous prévenir quand quelque chose bouge, pour que vous n'ayez pas à interroger son rapport : * Les **événements de changement** sont envoyés à votre `webhookUrl` quand les réponses à un prompt changent : votre marque apparaît ou disparaît, un concurrent prend l'avantage, ou un site est cité pour la première fois. * Les **alertes** envoient un e-mail aux administrateurs de votre compte quand le taux de mention de la marque sur les sept derniers jours passe sous `alertBelowPct`. ## Événements de changement Définissez `webhookUrl` quand vous [créez](/fr/monitors.md#créer-un-moniteur) ou mettez à jour un moniteur : ```bash theme={"theme":"css-variables"} curl -X PATCH https://api.querying.ai/v1/monitors/$MONITOR_ID \ -H "Authorization: Bearer $QUERYING_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "webhookUrl": "https://hooks.example.com/querying/monitors" }' ``` L'URL doit être en HTTPS sur un hôte public. Définissez-la avec une clé d'API : les événements sont signés avec la clé qui l'a définie, si bien qu'une requête sans clé (une session du tableau de bord) renvoie `400 VALIDATION_ERROR`. `webhookUrl: null` désactive les événements et efface l'état d'événements du moniteur ; les réactiver repart de son historique. ### Types d'événements | Événement | Envoyé quand | | - | - | | `monitor.mention.started` | Votre marque figure dans au moins trois des cinq dernières réponses à un prompt, après avoir figuré dans moins. | | `monitor.mention.stopped` | Votre marque tombe à deux ou moins des cinq dernières réponses à un prompt. | | `monitor.competitor.ahead` | Un concurrent figure dans au moins trois des cinq dernières réponses à un prompt, et dans plus de réponses que votre marque. | | `monitor.source.first_cited` | Une réponse cite un domaine que les réponses du moniteur n'avaient jamais cité. | Les événements de marque suivent chaque prompt séparément sur chaque moteur et, sur un moniteur en grille, à chaque point. L'état se lit sur les cinq dernières réponses : `samples: 5` donne donc un état complet en une exécution. * Un événement est envoyé une fois, quand l'état change. Une marque qui reste absente des réponses envoie un seul `monitor.mention.stopped`, puis plus rien jusqu'à son retour. * Un prompt a un état dès qu'il compte cinq réponses. Ce premier état sert de référence et n'envoie rien. * Un moniteur de catégorie n'a pas de marque propre et n'envoie que `monitor.source.first_cited`. Quand les événements commencent : * **Activer `webhookUrl` sur un moniteur qui a déjà des réponses** : l'état de chaque prompt est reconstruit à partir de ses cinq dernières réponses des 30 derniers jours, et chaque domaine déjà cité compte comme connu. Les événements commencent avec la réponse suivante. * **Créer un moniteur avec `webhookUrl`, ou l'activer avant qu'il n'existe des réponses** : la première exécution fixe les domaines connus, et `monitor.source.first_cited` compte les réponses des tâches créées après la soumission complète de cette exécution. Les événements de marque commencent dès qu'un prompt compte cinq réponses. ### Charge utile Chaque événement est un `POST` avec un corps JSON. Par exemple : ```json theme={"theme":"css-variables"} { "event": "monitor.mention.stopped", "id": "fd61d8f6-ebdf-4162-8b55-fd052c8502a9", "createdAt": "2026-10-10T03:12:44.120Z", "monitor": { "id": "d39b8de0-b159-4229-bf58-7064e5369db1", "name": "Earbud brand tracking" }, "data": { "engine": "CHATGPT", "prompt": "best wireless earbuds for commuting", "location": null, "taskId": "863edb44-fc62-40dd-a5be-2af9409d59b6", "answers": 5, "mentions": 2 } } ``` | Champ | Signification | | - | - | | `event` | Le type d'événement. | | `id` | L'id de l'événement, également envoyé dans l'en-tête `querying-webhook-id`. Dédupliquez sur cette valeur. | | `monitor` | L'`id` et le `name` du moniteur. | | `data.engine`, `data.prompt` | Le moteur et le prompt auxquels appartient la réponse. | | `data.location` | `{ latitude, longitude }` du point de la réponse, ou `null` sans localisation. | | `data.taskId` | La réponse qui a déclenché l'événement. Ouvrez-la avec [`GET /v1/monitors/{id}/answers/{taskId}`](/fr/monitors/evidence#lire-une-réponse). | | `data.answers`, `data.mentions` | Les réponses de l'état (5) et combien ont cité votre marque. Événements de mention et de concurrent uniquement. | | `data.competitor`, `data.competitorMentions` | Le concurrent et combien de réponses l'ont cité. `monitor.competitor.ahead` uniquement. | | `data.domain`, `data.url`, `data.label` | Le domaine nouvellement cité, la page citée et son libellé. `monitor.source.first_cited` uniquement, à la place des comptages. | ### Signature et nouvelles tentatives Les événements sont signés et retentés comme les webhooks de tâche : les trois mêmes en-têtes `querying-webhook-*`, le même schéma HMAC-SHA256 et le même calendrier de nouvelles tentatives. Vérifiez-les avec le code de [Webhooks](/fr/concepts/webhooks.md#vérifier-la-signature). Deux points diffèrent : * `querying-webhook-id` est l'`id` de l'événement. Dédupliquez sur cette valeur. * La clé HMAC est l'empreinte SHA-256 de la clé d'API qui a défini `webhookUrl`, et non de la clé d'une tâche. Après la rotation de la clé, renvoyez `webhookUrl` avec la nouvelle clé : les événements sont alors signés avec elle. Si la clé qui a défini `webhookUrl` est révoquée ou expire, les événements s'arrêtent : chacun est marqué `failed` avec la raison dans `delivery.lastError`, et rien n'est envoyé sans signature. ### Lister et renvoyer les événements `GET /v1/monitors/{id}/events` ([référence](/fr/api-reference/monitors/list-events.md)) liste les événements du plus récent au plus ancien. | Paramètre | Description | | - | - | | `limit` | 1 à 100, 50 par défaut. | | `type` | Un type d'événement. | | `cursor` | Le `nextCursor` de la page précédente. | La réponse contient `webhookUrl`, `nextCursor` (`null` sur la dernière page) et `events`. Chaque événement a `id`, `type`, `createdAt`, `data` (comme dans la charge utile) et `delivery` : | Champ | Signification | | - | - | | `delivery.status` | `pending` (en attente d'une première tentative ou d'une nouvelle tentative), `delivered` ou `failed` (tentatives épuisées, ou non livrable). | | `delivery.attempts` | Tentatives effectuées. | | `delivery.deliveredAt` | Le moment où un `2xx` a été reçu, ou `null`. | | `delivery.lastError` | Le dernier échec, comme `HTTP 500`, ou `null`. | `POST /v1/monitors/{id}/events/{eventId}/redeliver` ([référence](/fr/api-reference/monitors/redeliver-event.md)) renvoie un événement maintenant vers le `webhookUrl` actuel, avec une nouvelle série de tentatives, et renvoie l'événement avec son `delivery` mis à jour. Les événements déjà livrés peuvent aussi être renvoyés. Il renvoie `409 WEBHOOK_NOT_SET` quand le moniteur n'a pas de `webhookUrl` et `404 NOT_FOUND` pour un événement inconnu. Les événements sont conservés 30 jours. Un événement encore en cours de nouvelles tentatives est conservé jusqu'à la fin de celles-ci. ## Alertes Définissez `alertBelowPct` sur un moniteur de marque, un pourcentage entier de 1 à 100, pour recevoir un e-mail quand le taux de mention de la marque passe en dessous : ```bash theme={"theme":"css-variables"} curl -X PATCH https://api.querying.ai/v1/monitors/$MONITOR_ID \ -H "Authorization: Bearer $QUERYING_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "alertBelowPct": 40 }' ``` Comment l'alerte est décidée : * **Fenêtre** : les réponses notées des 7 derniers jours, sur tous les prompts et moteurs du moniteur. Le [rapport](/fr/monitors/reports.md) couvre 30 jours par défaut, ce qui évolue trop lentement pour prévenir qui que ce soit. * **Moment** : à chaque démarrage d'une exécution planifiée. La vérification lit les réponses déjà notées : elle reflète donc les exécutions précédentes. * **Échantillon minimal** : moins de 5 réponses notées dans la fenêtre ne déclenche jamais l'alerte. Un nouveau moniteur, ou un moniteur dont les moteurs échouent, reste silencieux. * **Franchissement, pas état** : l'alerte se déclenche quand le taux est sous le seuil et que l'alerte est armée, puis se désarme. Elle se réarme une fois le taux revenu au niveau du seuil ou au-dessus : un moniteur qui reste bas n'envoie donc qu'un e-mail, pas un à chaque exécution. Modifier `alertBelowPct` la réarme. L'e-mail est envoyé à chaque administrateur du compte qui paie le moniteur (pour un sous-compte, son compte parent). Il indique le taux arrondi, le seuil, la fenêtre et le nombre de réponses notées, et renvoie vers le moniteur dans le tableau de bord. Un moniteur de catégorie n'a pas de taux de marque : il refuse donc `alertBelowPct` avec `400 VALIDATION_ERROR`. `alertBelowPct: null` désactive l'alerte. ### Historique des alertes `GET /v1/monitors/{id}/alerts` ([référence](/fr/api-reference/monitors/get-alerts.md)) renvoie `alertBelowPct`, `armed` et `deliveries` : les 20 e-mails d'alerte les plus récents du moniteur, tests compris. Chaque envoi a `id`, `status` (`pending`, `sent` ou `failed`), `attempts`, `createdAt`, `sentAt`, `lastError` et `payload` (`monitorId`, `name`, `ratePct`, `threshold`, `windowDays`, `runs`). Les enregistrements d'envoi sont conservés 90 jours. ### Envoyer une alerte de test `POST /v1/monitors/{id}/alerts/test` ([référence](/fr/api-reference/monitors/test-alert.md)) met en file un e-mail de test par le même circuit d'envoi qu'une vraie alerte, avec « (test) » après le nom du moniteur, et renvoie `data.queued: true`. Vérifiez le résultat dans l'historique des alertes. Vous pouvez envoyer trois e-mails de test par moniteur toutes les cinq minutes ; au-delà, l'appel renvoie `429 RATE_LIMITED`. Un moniteur de catégorie renvoie `400 VALIDATION_ERROR`. ## Étapes suivantes > **[Webhooks](/fr/concepts/webhooks.md)** > > Signature, nouvelles tentatives et gestionnaires sûrs pour tous les webhooks. > **[Sources et réponses](/fr/monitors/evidence.md)** > > Ouvrez la réponse derrière un événement. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.