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
| Muster | Beschreibung |
|---|---|
* | 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:
{
"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
*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 MurphyHäufige Integrationen
GitHub-Webhooks
🔔 %action%: %repository.full_name%
%sender.login%: %commits.0.message%Sentry-Fehlertracking
Für eine interne Integration, die als Benachrichtigungsaktion (Issue-Alerts) genutzt wird:
🚨 %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
⚠️ %state%: %title%
%message%
Status: %status%Uptime Robot
🔴 %monitorFriendlyName%
Status: %alertTypeFriendlyName%
Details: %alertDetails%Erweiterte Pfad-Syntax
Für komplexe JSON-Extraktion verwenden wir die GJSON-Pfad-Syntax.
Nützliche Muster
| Muster | Beschreibung |
|---|---|
%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):
- Das
level-Feld in der eingehenden JSON-Payload - Das
default_leveldes Webhooks (wird beim Erstellen des Webhooks festgelegt) - Die Standardstufe der Anwendung
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:
[
{ "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:
curl -X POST "https://p4a.me/wh/YOUR_WEBHOOK_URL" \
-H "Content-Type: application/json" \
-d '{"event": {"title": "Test", "message": "Hello World"}}'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' }
})
});import requests
requests.post(
'https://p4a.me/wh/YOUR_WEBHOOK_URL',
json={'event': {'title': 'Test', 'message': 'Hello World'}}
)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.