Zum Inhalt springen

Webhook-Einstellungen ​

Erfahre, wie du Webhook-Nachrichtenvorlagen konfigurierst, um Daten aus eingehenden JSON-Payloads zu extrahieren.

Syntax der Nachrichtenvorlage ​

Beim Erstellen eines Webhooks legst du eine Nachrichtenvorlage fest. Sie bestimmt, wie eingehende JSON-Daten in Push-Benachrichtigungen formatiert werden.

Grundlegende Muster ​

MusterBeschreibung
*Gibt die gesamte JSON-Payload aus
%field%Extrahiert ein Feld der obersten Ebene
%object.field%Extrahiert ein verschachteltes Feld
%array.0%Holt das erste Element eines Arrays
%array.0.field%Holt ein Feld aus einem Array-Element
%%Ein wörtliches %. Nur nötig direkt vor einem Wort, auf das ein weiteres % folgt, etwa in %cpu%%%; ein % gefolgt von einem Leerzeichen, wie in 90% on %host%, bleibt unverändert

Ein Platzhalter enthält nie Leerzeichen, daher bleiben Prozentzeichen in normalem Text unverändert: CPU over 90% on %host% wird zu CPU over 90% on db-1.

Beispiele ​

Beispiel-JSON-Payload ​

Betrachte diese eingehende Webhook-Payload:

json
{
  "event": {
    "title": "New Order",
    "message": "A new order has been placed with ID 12345",
    "tags": ["order", "new"],
    "users": [
      {"first": "Dale", "last": "Murphy", "age": 44, "nets": ["ig", "fb", "tw"]},
      {"first": "Roger", "last": "Craig", "age": 68, "nets": ["fb", "tw"]},
      {"first": "Jane", "last": "Murphy", "age": 47, "nets": ["ig", "tw"]}
    ]
  }
}

Vorlagenkonfiguration ​

text
*
text
Title: %event.title%
Message: %event.message%
Tags: %event.tags%
Users: %event.users.0%
First user: %event.users.0.first% %event.users.0.last%

Ausgabeergebnis ​

Title: New Order
Message: A new order has been placed with ID 12345
Tags: ["order","new"]
Users: {"age":44,"first":"Dale","last":"Murphy","nets":["ig","fb","tw"]}
First user: Dale Murphy

Häufige Integrationen ​

GitHub-Webhooks ​

text
🔔 %action%: %repository.full_name%
%sender.login%: %commits.0.message%

Sentry-Fehlertracking ​

Für eine interne Integration, die als Benachrichtigungsaktion (Issue-Alerts) genutzt wird:

text
🚨 %data.event.title%
%data.event.culprit%
Rule: %data.triggered_rule%

Füge einen view-Button mit %data.event.web_url% hinzu, um das Issue zu öffnen. Das veraltete Webhooks-Plugin sendet eine andere Payload: Dort verwendest du %project_name%: %event.title% und %url%.

Grafana-Alerts ​

text
⚠️ %state%: %title%

%message%

Status: %status%

Uptime Robot ​

text
🔴 %monitorFriendlyName%
Status: %alertTypeFriendlyName%
Details: %alertDetails%

Erweiterte Pfad-Syntax ​

Für komplexe JSON-Extraktion verwenden wir die GJSON-Pfad-Syntax.

Nützliche Muster ​

MusterBeschreibung
%users.#%Anzahl der Array-Elemente
%users.#.first%Array aller first-Werte
%users.@reverse%Kehrt die Reihenfolge des Arrays um
%data.@pretty%Formatiert JSON übersichtlich (Pretty-Print)

Mehr erfahren

Vollständige Dokumentation: GJSON-Pfad-Syntax

Prioritätsstufe ​

Eingehende Payloads können ein level-Feld enthalten, um zu steuern, wie die Push-Benachrichtigung zugestellt wird – entweder ein Name (silent, low, default, high, critical) oder eine Ganzzahl (-2..2). Siehe Prioritätsstufen von Nachrichten.

Reihenfolge der Auflösung (der erste Treffer gewinnt):

  1. Das level-Feld in der eingehenden JSON-Payload
  2. Das default_level des Webhooks (wird beim Erstellen des Webhooks festgelegt)
  3. Die Standardstufe der Anwendung
  4. default (normal)

Anders als bei der direkten API ist die Webhook-Eingabe nachsichtig: Ein unbekannter level-Wert wird ignoriert (es gelten die Standardwerte), anstatt abgelehnt zu werden, sodass Alerts nie verloren gehen.

Aktionsbuttons ​

Ein Webhook kann jeder von ihm erzeugten Benachrichtigung bis zu 3 Aktionsbuttons anhängen. Setze das Feld actions (ein JSON-String) beim Erstellen oder Aktualisieren des Webhooks – siehe Webhook erstellen → Vorlage für Aktionsbuttons.

label und value unterstützen dieselben %field.path%-Platzhalter wie die Nachrichtenvorlage, sodass Buttons aus der eingehenden Payload aufgebaut werden können:

json
[
  { "type": "view", "label": "Open PR", "value": "%pull_request.html_url%" },
  { "type": "http", "label": "Merge", "value": "{\"url\":\"https://ci.example.com/merge/%pull_request.number%\",\"method\":\"POST\"}" }
]

Nach der Ersetzung wird jeder Button validiert (type ∈ view/http/copy, view und http benötigen eine http(s)-URL). Wie bei der Level-Auswertung ist das nachsichtig: Ein ungültiger Button wird einzeln verworfen, die übrigen Buttons und die Benachrichtigung werden trotzdem zugestellt.

Aktionsbuttons sind ein kostenpflichtiges Feature. In kostenlosen Tarifen werden sie entfernt, und die Benachrichtigung wird ohne sie zugestellt.

Nach dem Erstellen eines Webhooks kannst du ihn testen:

bash
curl -X POST "https://p4a.me/wh/YOUR_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"event": {"title": "Test", "message": "Hello World"}}'
javascript
await fetch('https://p4a.me/wh/YOUR_WEBHOOK_URL', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    event: { title: 'Test', message: 'Hello World' }
  })
});
python
import requests

requests.post(
    'https://p4a.me/wh/YOUR_WEBHOOK_URL',
    json={'event': {'title': 'Test', 'message': 'Hello World'}}
)
php
Http::post('https://p4a.me/wh/YOUR_WEBHOOK_URL', [
    'event' => [
        'title' => 'Test',
        'message' => 'Hello World',
    ],
]);

Dadurch wird eine Test-Benachrichtigung an deine Geräte gesendet, die deine konfigurierte Nachrichtenvorlage verwendet.

Pocket Alert Dokumentation