# 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:

```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

**Full JSON**

```text
*
```

**Extracted Fields**

```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](https://github.com/tidwall/gjson/blob/master/SYNTAX.md).

### 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) |

> **Tip: Mehr erfahren**
>
> Vollständige Dokumentation: [GJSON-Pfad-Syntax](https://github.com/tidwall/gjson/blob/master/SYNTAX.md)

## 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](https://info.pocketalert.app/api/messages/create.md#priority-levels).

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](https://info.pocketalert.app/api/webhooks/create.md#action-buttons-template).

`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:

**cURL**

```bash
curl -X POST "https://p4a.me/wh/YOUR_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"event": {"title": "Test", "message": "Hello World"}}'
```

**JavaScript**

```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**

```python
import requests

requests.post(
    'https://p4a.me/wh/YOUR_WEBHOOK_URL',
    json={'event': {'title': 'Test', 'message': 'Hello World'}}
)
```

**PHP**

```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.
