--- title: Webhook-Integration - Leitfaden für HTTP-Auslöser sidebarTitle: Webhooks description: "Echobell-Webhooks in Anwendungen und Dienste integrieren: HTTP-Methoden, Variablen, Vorlagen, Header und praxisnahe Beispiele für sofortige Benachrichtigungen." --- # Webhook-Integration 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. **Direct-Schlüssel verwendet?** Direct-Schlüssel sind jetzt Kanäle. Jeder Ihrer Schlüssel wurde in einen Kanal mit demselben Namen umgewandelt, und seine alte URL `https://hook.echobell.one/d/…` funktioniert weiterhin genau wie zuvor – Ihre Skripte müssen also nicht geändert werden. Neue Integrationen können die `/t/`-Webhook-URL des Kanals aus der App verwenden, die dieselben Felder akzeptiert. Auf der `/t/`-URL kann `notificationType` die Stufe, mit der Sie abonniert haben, nur senken (siehe [Benachrichtigungsstufe](#benachrichtigungsstufe)). Wenn ein Skript also `calling` anfordert, abonnieren Sie den Kanal mit dem Typ Anruf. ## 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](#benutzerdefinierte-vorlagen) 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. | Feld | Beschreibung | |---|---| | `title` | Titel der Benachrichtigung. Standardmäßig der Kanalname. | | `body` | Text der Benachrichtigung. Standardmäßig leer. | | `externalLink` | Ein Link, der beim Benachrichtigungseintrag angezeigt wird. Nützlich, um auf ein Dashboard, ein Log oder einen Pull Request zu verweisen. | | `notificationType` | `active`, `time-sensitive` oder `calling`. Kann die von jedem Abonnenten gewählte Stufe nur senken – siehe [Benachrichtigungsstufe](#benachrichtigungsstufe). | ### GET-Anfrage ```http GET https://hook.echobell.one/t/?title=Backup%20finished&body=Nightly%20backup%20completed ``` ### POST-Anfrage Senden Sie einen JSON-Body: ```http POST https://hook.echobell.one/t/ 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: ```bash curl -d "title=Hello&body=World" https://hook.echobell.one/t/ ``` ### 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: ```json { "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: ```json { "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](/de/docs/notification): 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: ```bash curl -d "title=Deploy finished&body=v2.1.0 is live¬ificationType=active" \ https://hook.echobell.one/t/ ``` 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: ```http GET https://hook.echobell.one/t/?server_name=Production&cpu_usage=95 ``` Oder in einem JSON-Body: ```http POST https://hook.echobell.one/t/ 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](/de/docs/template), und mit [Bedingungen](/de/docs/conditions) 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. ```http POST https://hook.echobell.one/t/ 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](/de/docs/conditions). ## 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](#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](/de/docs/support) oder kontaktieren Sie uns unter echobell@weelone.com.