Webhook-Integration - Leitfaden für HTTP-Auslöser

Webhooks sind die vielseitigste Möglichkeit, Echobell-Benachrichtigungen auszulösen. Dieser umfassende Leitfaden behandelt alles, was Sie wissen müssen, um webhook-basierte Warnungen in Ihre Systeme zu integrieren - von grundlegenden Konzepten bis zu fortgeschrittenen Nutzungsmustern.

Was ist ein Webhook?

Ein Webhook ist eine Möglichkeit für eine Anwendung, anderen Anwendungen Echtzeitinformationen bereitzustellen. Es ist wie eine Telefonnummer, die Sie jemandem geben - wenn diese Person die Nummer anruft, klingelt Ihr Telefon. In der digitalen Welt sendet ein System, wenn etwas passiert, eine HTTP-Anfrage an eine URL (den Webhook), die Sie bereitgestellt haben, und löst damit eine Aktion in Ihrem System aus.

Wenn zum Beispiel die CPU-Auslastung Ihres Servers zu hoch wird, kann Ihr Überwachungssystem die Webhook-URL von Echobell aufrufen, die dann eine Benachrichtigung auslöst, um Sie zu alarmieren. Dies geschieht automatisch und in Echtzeit, ohne dass Sie die CPU-Auslastung selbst ständig überprüfen müssen.

Übersicht

Über Kanäle empfängt Echobell Webhooks. Jeder Kanal hat seine eigene Webhook-URL, und wenn diese URL aufgerufen wird, sendet der Kanal eine Benachrichtigung an alle seine Abonnenten.

Zum Erstellen eines Kanals genügt ein Name. Standardmäßig zeigt der Kanal title, body und externalLink jeder Anfrage genau so an, wie sie gesendet wurden – praktisch für Ihre eigenen Skripte, Cronjobs und CI-Schritte. Kommt die Anfrage von einem anderen Dienst, können Sie eine benutzerdefinierte Vorlage aktivieren und die Benachrichtigung stattdessen aus den Daten der Anfrage erstellen.

Webhook-URL-Format

https://hook.echobell.one/t/{kanal-token}

Sie finden die Webhook-URL Ihres Kanals in der Kanaldetailansicht der Echobell-App.

Webhook-Anfragen ausführen

Standardmäßig liest ein Kanal vier Felder aus jeder Anfrage. Bei Feldnamen wird die Groß-/Kleinschreibung nicht beachtet (title, Title und TITLE sind dasselbe Feld), und sie können in der Abfragezeichenfolge eines GET oder in einem JSON- oder formularcodierten POST-Body stehen.

GET-Anfrage

GET https://hook.echobell.one/t/<channel-token>?title=Backup%20finished&body=Nightly%20backup%20completed

POST-Anfrage

Senden Sie einen JSON-Body:

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "title": "CPU alert",
  "body": "Production CPU usage reached 95%",
  "externalLink": "https://dashboard.example.com/alerts/123"
}

Oder einen formularcodierten Body, wie ihn curl -d sendet:

curl -d "title=Hello&body=World" https://hook.echobell.one/t/<channel-token>

URL im Browser öffnen

Ein GET ohne Abfragezeichenfolge und ohne Body – das, was ein Browser oder die Linkvorschau einer Chat-App sendet – benachrichtigt niemanden. Stattdessen antwortet der Kanal mit einer kurzen Beschreibung der Felder, die er akzeptiert:

{
  "success": true,
  "notificationTriggered": false,
  "message": "This is an Echobell channel webhook. It pushes a notification to the channel's subscribers. Send a title or a body to trigger one.",
  "usage": { "...": "..." }
}

Fügen Sie title oder body hinzu, um eine Benachrichtigung zu senden. Ein POST benachrichtigt immer, auch mit leerem Body (der Titel ist dann der Kanalname).

Nur POST

Jeder Kanal hat in der Echobell-App unter Erweiterte Einstellungen einen Schalter Nur POST. Er ist standardmäßig aus.

Ist er an, kann nur POST den Kanal auslösen. Ein GET auf die Webhook-URL wird mit 405 Method Not Allowed abgelehnt, und es wird keine Benachrichtigung gesendet:

{
  "success": false,
  "notificationTriggered": false,
  "message": "This trigger only accepts POST requests; GET triggering is disabled in its settings."
}

HEAD-Anfragen sind davon nicht betroffen — sie antworten mit 200 und lösen nie eine Benachrichtigung aus, egal ob Nur POST an oder aus ist.

Schalte es ein, wenn die Webhook-URL an einem Ort landet, der Links automatisch abruft — eine Chat-Nachricht, eine Wiki-Seite, die Adressleiste des Browsers — damit eine Vorschau oder ein Öffnen der URL keinen Alarm auslösen kann. Lass es aus, wenn einer deiner Aufrufer den Kanal per GET auslöst.

Benachrichtigungsstufe

Jeder, der einen Kanal abonniert, wählt dafür in der App einen Benachrichtigungstyp: Normal (active), Zeitkritisch oder Anruf. Diese Wahl ist die höchste Stufe, mit der der Kanal ihn erreichen kann. Eine Anfrage kann notificationType senden, um eine niedrigere Stufe anzufordern, aber niemals eine höhere.

Abonnieren Sie zum Beispiel Ihren Kanal „Production“ mit dem Typ Anruf. Anfragen zu Ausfällen lassen notificationType weg und klingeln daher wie ein Telefonanruf. Routineereignisse, etwa ein abgeschlossenes Deployment, senden notificationType=active und kommen als normale Benachrichtigung an:

curl -d "title=Deploy finished&body=v2.1.0 is live&notificationType=active" \
  https://hook.echobell.one/t/<channel-token>

Ein Teammitglied, das denselben Kanal mit dem Typ Zeitkritisch abonniert hat, erhält den Ausfall als zeitkritische Benachrichtigung, niemals als Anruf.

Kanäle, bei denen Eigene Vorlage aktiviert ist, ignorieren notificationType in der Anfrage: Jeder Abonnent erhält immer die Stufe, die er gewählt hat.

Benutzerdefinierte Vorlagen

Standardmäßig zeigt ein Kanal title, body und externalLink jeder Anfrage an. Kommt die Anfrage von einem Dienst, dessen Payload Sie nicht ändern können – einem Monitoring-Tool, einem CI-System, einem Shop –, aktivieren Sie in den Einstellungen des Kanals unter Erweiterte Einstellungen die Option Eigene Vorlage und schreiben eine Titel- und eine Textvorlage. Der Kanal erstellt dann jede Benachrichtigung aus diesen Vorlagen, und jeder Abfrageparameter und jedes JSON-Feld der Anfrage wird zu einer Variablen.

Übergeben Sie Variablen über Abfrageparameter:

GET https://hook.echobell.one/t/<channel-token>?server_name=Production&cpu_usage=95

Oder in einem JSON-Body:

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Production",
  "cpu_usage": 95
}

Vorlagenvariablen

Verwenden Sie die Variablen in Ihren Benachrichtigungsvorlagen mit der {{variablenName}}-Syntax:

Titel: Server {{server_name}} Alarm
Text: CPU-Auslastung hat {{cpu_usage}}% erreicht

Bei Auslösung werden diese Vorlagen mit den in Ihrer Webhook-Anfrage bereitgestellten Werten gefüllt. Die vollständige Syntax finden Sie unter Vorlagen, und mit Bedingungen legen Sie fest, welche Anfragen benachrichtigen.

Spezielle Variablen

• externalLink: Wenn in der Anfrage enthalten, erstellt dies einen klickbaren Link in der Benachrichtigungsprotokollansicht, sofern der Kanal keine eigene Vorlage für den externen Link hat.

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Production",
  "cpu_usage": 95,
  "externalLink": "https://dashboard.example.com/alerts/123"
}

Systemzeit‑Variablen (UTC)

Zusätzlich zu gesendeten Daten stellt Echobell schreibgeschützte Systemzeit‑Variablen bereit, die in Vorlagen und Bedingungen immer verfügbar sind (UTC). Flache Felder umfassen date, time, year, month, dayOfWeek, hour, minute und second. Andere – wie sys.dayOfWeekName, sys.epochMs und sys.epochSeconds – sind nur unter dem sys.-Namespace verfügbar. Die vollständige Liste und Beispiele finden Sie unter Bedingungen.

Häufige Anwendungsfälle

Webhooks sind besonders nützlich für:

• Server-Überwachung und Alarme
• CI/CD-Pipeline-Benachrichtigungen
• IoT-Gerätestatus-Updates
• Anwendungsfehler-Tracking
• E-Commerce-Bestellbenachrichtigungen
• Automatisierte Systemalarme

Beste Praktiken

1. Fehlerbehandlung: Echobell beantwortet jeden Webhook-Aufruf mit einem HTTP-Status und einem JSON-Body. Prüfen Sie zuerst den HTTP-Status und dann notificationTriggered, um zu wissen, ob eine Benachrichtigung verschickt wurde:
   • 200 OK: Die Anfrage wurde verarbeitet. notificationTriggered: true bedeutet, dass eine Benachrichtigung verschickt wurde. notificationTriggered: false bedeutet, dass bewusst nichts verschickt wurde: Die Bedingungen des Kanals trafen nicht zu (conditionsMet: false), oder ein leeres GET hat die Nutzungsbeschreibung erhalten.
   • 400 Bad Request: Das Token in der URL hat die falsche Länge.
   • 404 Not Found: Kein Kanal hat dieses Token (code: "TRIGGER_TOKEN_NOT_FOUND"; bei einer alten /d/-URL DIRECT_KEY_NOT_FOUND). Der Kanal wurde gelöscht oder seine Webhook-URL zurückgesetzt.
   • 405 Method Not Allowed: Nur POST ist aktiviert und die Anfrage war kein POST.
   • 413 Payload Too Large: Der Anfrage-Body ist größer als 1 MiB.
   • 429 Too Many Requests: Mehr als 120 Anfragen pro Minute an dieselbe Webhook-URL. Die Antwort enthält einen Retry-After-Header (in Sekunden); warten Sie so lange, bevor Sie es erneut versuchen.
   • 500: Vorübergehendes Serverproblem, mit exponentiellem Backoff erneut versuchen.
2. Ratenbegrenzung: Implementieren Sie angemessene Verzögerungen zwischen Webhook-Aufrufen, um eine Überlastung Ihres Benachrichtigungssystems zu vermeiden. Jede Webhook-URL nimmt bis zu 120 Anfragen pro Minute an; darüber hinaus antwortet Echobell mit 429.
3. Datensicherheit: Teilen Sie Webhook-URLs nur mit vertrauenswürdigen Systemen und Diensten
4. Tests: Testen Sie Ihre Webhook-Integration mit minimalen Daten, bevor Sie sie in der Produktion implementieren

Datenschutz und Sicherheit

Beachten Sie, dass:

• Webhook-URLs als Geheimnisse behandelt werden sollten
• Nur notwendige Daten in Webhook-Anfragen gesendet werden sollten
• Alle Benachrichtigungsinhalte lokal auf den Geräten der Abonnenten gespeichert werden
• Unsere Server nur die Webhook-Anfrage verarbeiten und Benachrichtigungen weiterleiten

Fehlerbehebung

Wenn Ihre Webhooks nicht wie erwartet funktionieren:

1. Überprüfen Sie, ob die Webhook-URL korrekt ist
2. Prüfen Sie, ob der Kanal aktiv ist
3. Stellen Sie sicher, dass Ihr JSON-Payload korrekt formatiert ist (für POST-Anfragen)
4. Bestätigen Sie, dass alle erforderlichen Variablen in Ihren Vorlagen bereitgestellt werden (Kanäle mit benutzerdefinierter Vorlage)
5. Überprüfen Sie, ob der Kanal aktive Abonnenten hat

Brauchen Sie Hilfe? Besuchen Sie unser Support-Center oder kontaktieren Sie uns unter echobell@weelone.com.