Monitor-Ereignisse und Alarme: Webhooks und E-Mail-Benachrichtigungen

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 oder aktualisieren:

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:

{
  "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}`.
`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. 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) 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) 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:

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 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) 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) 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.

Erste Schritte

Grundlagen

Antwort-Engines

Suche und Webdaten

Anfrageoptionen

Recherche

GEO-Monitoring

Konto und Daten

Monitor-Ereignisse und Alarme: Webhooks und E-Mail-Benachrichtigungen

Änderungsereignisse

Ereignistypen

Payload

Signatur und Wiederholungen

Ereignisse auflisten und erneut senden

Alarme

Alarmhistorie

Einen Testalarm senden

Nächste Schritte

Webhooks

Quellen und Antworten

​Änderungsereignisse

​Ereignistypen

​Payload

​Signatur und Wiederholungen

​Ereignisse auflisten und erneut senden

​Alarme

​Alarmhistorie

​Einen Testalarm senden

​Nächste Schritte

Webhooks

Quellen und Antworten

Änderungsereignisse

Ereignistypen

Payload

Signatur und Wiederholungen

Ereignisse auflisten und erneut senden

Alarme

Alarmhistorie

Einen Testalarm senden

Nächste Schritte