> ## 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. # Monitor-Ereignisse und Alarme: Webhooks und E-Mail-Benachrichtigungen > Erhalten Sie einen signierten Webhook, wenn sich die Antworten eines Monitors ändern, und eine E-Mail, wenn Ihre Nennungsquote unter eine Schwelle fällt. Ein Monitor kann Ihnen mitteilen, wenn sich etwas bewegt, damit Sie seinen Bericht nicht abfragen müssen: * **Änderungsereignisse** gehen an Ihre `webhookUrl`, wenn sich die Antworten auf einen Prompt ändern: Ihre Marke taucht auf oder verschwindet, ein Wettbewerber zieht vorbei, oder eine Website wird zum ersten Mal zitiert. * **Alarme** schicken den Admins Ihres Kontos eine E-Mail, wenn die Nennungsquote der Marke über die letzten sieben Tage unter `alertBelowPct` fällt. ## Änderungsereignisse Setzen Sie `webhookUrl`, wenn Sie einen Monitor [anlegen](/de/monitors.md#einen-monitor-anlegen) oder aktualisieren: ```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" }' ``` Die URL muss HTTPS auf einem öffentlichen Host sein. Setzen Sie sie mit einem API-Schlüssel: Ereignisse werden mit dem Schlüssel signiert, der sie gesetzt hat, daher liefert eine Anfrage ohne Schlüssel (eine Dashboard-Sitzung) `400 VALIDATION_ERROR`. `webhookUrl: null` schaltet Ereignisse ab und verwirft den Ereigniszustand des Monitors; beim erneuten Einschalten beginnt er wieder bei seiner Historie. ### Ereignistypen | Ereignis | Gesendet, wenn | | - | - | | `monitor.mention.started` | Ihre Marke steht in mindestens drei der letzten fünf Antworten auf einen Prompt, nachdem es weniger waren. | | `monitor.mention.stopped` | Ihre Marke fällt auf zwei oder weniger der letzten fünf Antworten auf einen Prompt. | | `monitor.competitor.ahead` | Ein Wettbewerber steht in mindestens drei der letzten fünf Antworten auf einen Prompt und in mehr davon als Ihre Marke. | | `monitor.source.first_cited` | Eine Antwort zitiert eine Domain, die die Antworten des Monitors noch nie zitiert haben. | Marken-Ereignisse verfolgen jeden Prompt getrennt auf jeder Engine und bei einem Raster-Monitor an jedem Punkt. Der Zustand wird aus den letzten fünf Antworten gelesen, mit `samples: 5` liefert also ein Lauf einen vollständigen Zustand. * Ein Ereignis wird einmal gesendet, wenn sich der Zustand ändert. Bleibt eine Marke den Antworten fern, kommt ein `monitor.mention.stopped` und danach nichts mehr, bis sie zurückkehrt. * Ein Prompt hat einen Zustand, sobald er fünf Antworten hat. Dieser erste Zustand ist die Ausgangsbasis und sendet nichts. * Ein Kategorie-Monitor hat keine eigene Marke und sendet nur `monitor.source.first_cited`. Wann Ereignisse beginnen: * **`webhookUrl` für einen Monitor einschalten, der schon Antworten hat**: Der Zustand jedes Prompts wird aus seinen letzten fünf Antworten der vergangenen 30 Tage rekonstruiert, und jede bereits zitierte Domain gilt als bekannt. Ereignisse beginnen mit der nächsten Antwort. * **Einen Monitor mit `webhookUrl` anlegen oder sie einschalten, bevor es Antworten gibt**: Der erste Lauf legt die bekannten Domains fest, und `monitor.source.first_cited` zählt Antworten aus Tasks, die erstellt wurden, nachdem dieser Lauf vollständig eingereicht ist. Marken-Ereignisse beginnen, sobald ein Prompt fünf Antworten hat. ### Payload Jedes Ereignis ist ein `POST` mit JSON-Body. Zum Beispiel: ```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 } } ``` | Feld | Bedeutung | | - | - | | `event` | Der Ereignistyp. | | `id` | Die id des Ereignisses, auch als Header `querying-webhook-id` gesendet. Deduplizieren Sie darüber. | | `monitor` | `id` und `name` des Monitors. | | `data.engine`, `data.prompt` | Engine und Prompt, zu denen die Antwort gehört. | | `data.location` | `{ latitude, longitude }` des Punkts der Antwort, oder `null` ohne Standort. | | `data.taskId` | Die Antwort, die das Ereignis ausgelöst hat. Öffnen Sie sie mit [`GET /v1/monitors/{id}/answers/{taskId}`](/de/monitors/evidence#eine-antwort-lesen). | | `data.answers`, `data.mentions` | Antworten im Zustand (5) und wie viele davon Ihre Marke nannten. Nur Nennungs- und Wettbewerber-Ereignisse. | | `data.competitor`, `data.competitorMentions` | Der Wettbewerber und wie viele der Antworten ihn nannten. Nur `monitor.competitor.ahead`. | | `data.domain`, `data.url`, `data.label` | Die neu zitierte Domain, die zitierte Seite und ihr Label. Nur `monitor.source.first_cited`, anstelle der Zählungen. | ### Signatur und Wiederholungen Ereignisse werden wie Task-Webhooks signiert und wiederholt: dieselben drei `querying-webhook-*`-Header, dasselbe HMAC-SHA256-Verfahren und derselbe Wiederholungsplan. Prüfen Sie sie mit dem Code unter [Webhooks](/de/concepts/webhooks.md#signatur-prüfen). Zwei Dinge unterscheiden sich: * `querying-webhook-id` ist die `id` des Ereignisses. Deduplizieren Sie darüber. * Der HMAC-Schlüssel ist der SHA-256-Digest des API-Schlüssels, der `webhookUrl` gesetzt hat, nicht der eines Tasks. Nach dem Rotieren des Schlüssels senden Sie `webhookUrl` erneut mit dem neuen Schlüssel, und Ereignisse werden damit signiert. Wird der Schlüssel, der `webhookUrl` gesetzt hat, widerrufen oder läuft er ab, stoppen die Ereignisse: Jedes wird als `failed` markiert, mit dem Grund in `delivery.lastError`, und nichts wird unsigniert gesendet. ### Ereignisse auflisten und erneut senden `GET /v1/monitors/{id}/events` ([Referenz](/de/api-reference/monitors/list-events.md)) listet Ereignisse, neueste zuerst. | Parameter | Beschreibung | | - | - | | `limit` | 1–100, Standard 50. | | `type` | Ein Ereignistyp. | | `cursor` | Das `nextCursor` der vorherigen Seite. | Die Antwort enthält `webhookUrl`, `nextCursor` (`null` auf der letzten Seite) und `events`. Jedes Ereignis hat `id`, `type`, `createdAt`, `data` (wie in der Payload) und `delivery`: | Feld | Bedeutung | | - | - | | `delivery.status` | `pending` (wartet auf einen ersten Versuch oder eine Wiederholung), `delivered` oder `failed` (Wiederholungen erschöpft oder nicht zustellbar). | | `delivery.attempts` | Unternommene Versuche. | | `delivery.deliveredAt` | Wann ein `2xx` empfangen wurde, oder `null`. | | `delivery.lastError` | Der letzte Fehler, etwa `HTTP 500`, oder `null`. | `POST /v1/monitors/{id}/events/{eventId}/redeliver` ([Referenz](/de/api-reference/monitors/redeliver-event.md)) sendet ein Ereignis jetzt erneut an die aktuelle `webhookUrl`, mit neu beginnenden Wiederholungen, und liefert das Ereignis mit aktualisiertem `delivery`. Auch zugestellte Ereignisse lassen sich erneut senden. Der Aufruf liefert `409 WEBHOOK_NOT_SET`, wenn der Monitor keine `webhookUrl` hat, und `404 NOT_FOUND` für ein unbekanntes Ereignis. Ereignisse werden 30 Tage aufbewahrt. Ein Ereignis, das noch wiederholt wird, bleibt bis zum Ende seiner Wiederholungen erhalten. ## Alarme Setzen Sie `alertBelowPct` an einem Marken-Monitor, einen ganzzahligen Prozentwert von 1 bis 100, um eine E-Mail zu erhalten, wenn die Nennungsquote der Marke darunter fällt: ```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 }' ``` So wird über den Alarm entschieden: * **Fenster**: die bewerteten Antworten der letzten 7 Tage, über alle Prompts und Engines des Monitors. Der [Bericht](/de/monitors/reports.md) nutzt standardmäßig 30 Tage, was sich zu langsam bewegt, um rechtzeitig zu warnen. * **Zeitpunkt**: jedes Mal, wenn ein geplanter Lauf startet. Die Prüfung liest die bereits bewerteten Antworten, spiegelt also die vorherigen Läufe. * **Mindeststichprobe**: Bei weniger als 5 bewerteten Antworten im Fenster wird nie ausgelöst. Ein neuer Monitor oder einer, dessen Engines fehlschlagen, bleibt still. * **Unterschreitung, nicht Zustand**: Der Alarm löst aus, wenn die Quote unter der Schwelle liegt und der Alarm scharf ist, und wird danach entschärft. Er wird wieder scharf, sobald die Quote wieder bei oder über der Schwelle liegt; ein dauerhaft niedriger Monitor schickt also eine E-Mail, nicht eine pro Lauf. Eine Änderung von `alertBelowPct` macht ihn wieder scharf. Die E-Mail geht an jeden Admin des Kontos, das den Monitor bezahlt (bei einem Unterkonto an dessen Hauptkonto). Sie nennt die gerundete Quote, die Schwelle, das Fenster und die Zahl der bewerteten Antworten und verlinkt auf den Monitor im Dashboard. Ein Kategorie-Monitor hat keine Markenquote und lehnt `alertBelowPct` daher mit `400 VALIDATION_ERROR` ab. `alertBelowPct: null` schaltet den Alarm ab. ### Alarmhistorie `GET /v1/monitors/{id}/alerts` ([Referenz](/de/api-reference/monitors/get-alerts.md)) liefert `alertBelowPct`, `armed` und `deliveries`: die 20 neuesten Alarm-E-Mails des Monitors, Tests eingeschlossen. Jede Zustellung hat `id`, `status` (`pending`, `sent` oder `failed`), `attempts`, `createdAt`, `sentAt`, `lastError` und `payload` (`monitorId`, `name`, `ratePct`, `threshold`, `windowDays`, `runs`). Zustelldatensätze werden 90 Tage aufbewahrt. ### Einen Testalarm senden `POST /v1/monitors/{id}/alerts/test` ([Referenz](/de/api-reference/monitors/test-alert.md)) reiht eine Test-E-Mail über denselben Zustellweg wie ein echter Alarm ein, mit „(test)“ nach dem Monitornamen, und liefert `data.queued: true`. Prüfen Sie das Ergebnis in der Alarmhistorie. Sie können drei Test-E-Mails pro Monitor alle fünf Minuten senden; darüber hinaus folgt `429 RATE_LIMITED`. Ein Kategorie-Monitor liefert `400 VALIDATION_ERROR`. ## Nächste Schritte > **[Webhooks](/de/concepts/webhooks.md)** > > Signatur, Wiederholungen und sichere Handler für jeden Webhook. > **[Quellen und Antworten](/de/monitors/evidence.md)** > > Die Antwort hinter einem Ereignis öffnen. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.