# Paramètres des webhooks

Découvrez comment configurer les modèles de message des webhooks pour extraire des données des charges utiles JSON entrantes.

## Syntaxe des modèles de message

Lors de la création d’un webhook, vous définissez un modèle de message qui détermine comment les données JSON entrantes sont mises en forme dans les notifications.

### Motifs de base

| Motif | Description |
|---------|-------------|
| `*` | Affiche la charge utile JSON complète |
| `%field%` | Extrait un champ de premier niveau |
| `%object.field%` | Extrait un champ imbriqué |
| `%array.0%` | Récupère le premier élément d’un tableau |
| `%array.0.field%` | Récupère un champ d’un élément de tableau |
| `%%` | Un `%` littéral. Nécessaire uniquement juste avant un mot suivi d’un autre `%`, comme dans `%cpu%%%` ; un `%` suivi d’un espace, comme dans `90% on %host%`, reste tel quel |

Un espace réservé ne contient jamais d’espaces : les signes de pourcentage présents dans un texte ordinaire sont donc laissés intacts. `CPU over 90% on %host%` s’affiche comme `CPU over 90% on db-1`.

## Exemples

### Exemple de charge utile JSON

Prenons cette charge utile de webhook entrante :

```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"]}
    ]
  }
}
```

### Configuration du modèle

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

### Résultat

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

## Intégrations courantes

### Webhooks GitHub

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

### Suivi des erreurs Sentry

Pour une intégration interne utilisée comme action d’alerte (alertes sur les problèmes) :

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

Ajoutez un bouton `view` avec `%data.event.web_url%` pour ouvrir le problème. L’extension Webhooks héritée envoie une charge utile différente : utilisez alors `%project_name%: %event.title%` et `%url%`.

### Alertes Grafana

```text
⚠️ %state%: %title%

%message%

Status: %status%
```

### Uptime Robot

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

## Syntaxe de chemin avancée

Pour l’extraction JSON complexe, nous utilisons la [syntaxe de chemin GJSON](https://github.com/tidwall/gjson/blob/master/SYNTAX.md).

### Motifs utiles

| Motif | Description |
|---------|-------------|
| `%users.#%` | Nombre d’éléments du tableau |
| `%users.#.first%` | Tableau de toutes les valeurs `first` |
| `%users.@reverse%` | Inverse l’ordre du tableau |
| `%data.@pretty%` | Affiche le JSON mis en forme |

> **Tip: En savoir plus**
>
> Documentation complète : [syntaxe de chemin GJSON](https://github.com/tidwall/gjson/blob/master/SYNTAX.md)

## Niveau de priorité

Les charges utiles entrantes peuvent contenir un champ `level` pour contrôler la manière dont la notification push est remise : un nom (`silent`, `low`, `default`, `high`, `critical`) ou un entier (`-2`..`2`). Voir [Niveaux de priorité des messages](https://info.pocketalert.app/api/messages/create.md#priority-levels).

Ordre de résolution (la première correspondance l’emporte) :

1. Le champ `level` de la charge utile JSON entrante
2. Le `default_level` du webhook (défini lors de la création du webhook)
3. Le niveau par défaut de l’application
4. `default` (normal)

Contrairement à l’API directe, l’entrée des webhooks est tolérante : une valeur `level` non reconnue est ignorée (les valeurs par défaut s’appliquent) au lieu d’être rejetée, afin que les alertes ne soient jamais perdues.

## Boutons d’action

Un webhook peut associer jusqu’à 3 boutons d’action à chaque notification qu’il génère. Définissez le champ `actions` (une chaîne JSON) lors de la création ou de la mise à jour du webhook — voir [Créer un webhook → Modèle des boutons d’action](https://info.pocketalert.app/api/webhooks/create.md#action-buttons-template).

`label` et `value` acceptent les mêmes espaces réservés `%field.path%` que le modèle de message, ce qui permet de construire les boutons à partir de la charge utile entrante :

```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\"}" }
]
```

Après substitution, chaque bouton est validé (`type` ∈ `view`/`http`/`copy`, `view` et `http` nécessitent une URL `http(s)`). Comme pour l’analyse du niveau, ce traitement est tolérant : un bouton invalide est supprimé individuellement, tandis que les autres boutons et la notification sont tout de même remis.

Les boutons d’action sont une fonctionnalité payante. Sur l’offre gratuite, ils sont retirés et la notification est remise sans eux.

Après avoir créé un webhook, vous pouvez le tester :

**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',
    ],
]);
```

Cela enverra une notification de test à vos appareils en utilisant le modèle de message configuré.
