Webhook-Integrationsleitfaden

Wenn Sie einen Webhook einrichten, sendet Miharu seine Überwachungsergebnisse (Systemalerts) als HTTP POST mit JSON-Body an eine URL Ihrer Wahl. So verbinden Sie Zapier, Make, n8n, Ihren eigenen Server und mehr und verarbeiten Benachrichtigungen ganz nach Ihren Vorstellungen.

Diese Funktion richtet sich an Entwickler und erfahrene Nutzer. Auf Ihrer Seite wird ein empfangender Endpunkt benötigt.

1. Einrichtung

1. 1Öffnen Sie in der App „Externe Benachrichtigungen“ → „Webhook“.
2. 2Geben Sie die Webhook-URL des Ziels ein (muss mit https:// beginnen).
3. 3Legen Sie bei Bedarf den Benachrichtigungsfilter fest (z. B. nur eine bestimmte Überwachungsgruppe).
4. 4Beim Speichern wird eine Testbenachrichtigung zur Bestätigung zugestellt.

2. HTTP-Spezifikation

Es wird kein Signatur-Header (z. B. HMAC) gesendet. Die Webhook-URL selbst ist das Geheimnis (siehe Sicherheit unten).

3. Payload (gemeinsame Felder)

4. Ereignistypen und detail

Das diff bei page_changed

diff ist ein Array der Änderungen. Jedes Element ist eines der folgenden:

• { "op": "added", "text": "..." }… eine hinzugefügte Zeile
• { "op": "removed", "text": "..." }… eine entfernte Zeile
• { "op": "replaced", "before": "...", "after": "..." }… eine ersetzte Zeile

Ist truncated gleich true, war der Unterschied groß und wurde teilweise ausgelassen.

5. Beispiele

{
  "source": "miharu",
  "version": "1",
  "id": "5c2e1b7a-9f3d-5a6b-8c4e-1d2f3a4b5c6d",
  "timestamp": "2026-05-22T01:23:45Z",
  "language": "de",
  "event": "page_changed",
  "monitor": { "id": "abc123", "name": "Produktseite", "url": "https://example.com/item" },
  "message": { "body": "Die Seite wurde aktualisiert.", "label": "Aktualisierung" },
  "detail": {
    "diff": [
      { "op": "replaced", "before": "Nicht verfügbar", "after": "Verfügbar" },
      { "op": "added", "text": "Heute eingetroffen" }
    ],
    "truncated": false
  }
}

{
  "source": "miharu", "version": "1", "id": "…",
  "timestamp": "2026-05-22T01:23:45Z", "language": "de",
  "event": "keyword_hit",
  "monitor": { "id": "abc123", "name": "Verfügbarkeitsseite", "url": "https://example.com/stock" },
  "message": { "body": "Ein Schlüsselwort wurde erkannt.", "label": "Schlüsselwort" },
  "detail": { "hits": [ { "keywords": ["eingetroffen"], "excerpts": ["…heute eingetroffen…"] } ] }
}

{
  "…": "…",
  "event": "new_link",
  "message": { "body": "Ein neuer Link wurde erkannt.", "label": "Neuer Link" },
  "detail": { "links": [ { "text": "Ankündigung eines neuen Produkts", "url": "https://example.com/news/123" } ] }
}

{
  "…": "…",
  "event": "price_changed",
  "message": { "body": "„Preis“ hat sich geändert.\n\n1980 → 1480", "label": "Preis/Wert" },
  "detail": { "target_name": "Preis", "before": "1980", "after": "1480" }
}

6. Idempotenz (Duplikatserkennung)

Dasselbe Ereignis kommt immer mit derselben id an, auch bei Wiederholungen (derselbe Wert steht auch im Header X-Miharu-Notification-Id). Nutzen Sie id auf Ihrer Seite, um doppelte Verarbeitung zu vermeiden.

7. Sicherheit

• HTTPS erforderlich (nur https://-URLs können eingetragen werden).
• Es wird kein Signatur-Header gesendet – behandeln Sie deshalb die Webhook-URL selbst als Geheimnis (wird sie bekannt, könnten Dritte gefälschte Benachrichtigungen senden).
• Nehmen Sie bei Bedarf ein zufälliges Token in die URL auf (z. B. https://example.com/hook/<zufall>) und prüfen Sie es auf Ihrer Seite.
• Als grober Hinweis auf den Absender lassen sich User-Agent: Miharu-Webhook/1.0 und die X-Miharu-*-Header auswerten (nur ergänzend).

8. Integrationen

Erzeugen Sie in Ihrem Dienst eine Empfangs-URL und tragen Sie sie in Miharu als Webhook-URL ein.

• Zapier: die URL aus „Webhooks by Zapier“ → „Catch Hook“
• Make: die URL eines „Custom webhook“
• n8n: die URL eines „Webhook“-Nodes
• Eigener Server: ein Endpunkt, der den JSON-Body annimmt und 2xx zurückgibt

9. Einschränkungen

• Per Webhook kommen Systemalerts (die Erkennungen) und Systembenachrichtigungen an.
• Lange Unterschiede oder Texte können gekürzt werden (z. B. truncated: true).
• Mit dem Benachrichtigungsfilter beschränken Sie den Versand auf eine bestimmte Überwachungsgruppe.

10. Fehlersuche

• Beginnt die URL mit https://?
• Gibt Ihr Endpunkt 2xx zurück? (Weiterleitungen und Fehler gelten als Fehlschlag.)
• Wurde der Versand nach wiederholten Antworten ungleich 2xx gestoppt? Prüfen Sie den Status in der App und richten Sie den Webhook erneut ein.
• Dauert die Verarbeitung länger als 10 Sekunden (Timeout)? Geben Sie sofort 2xx zurück und verarbeiten Sie asynchron.

Ihre Hinweise und Wünsche senden Sie über „Feedback & Vorschläge“ in der App.