Aller au contenu

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 ​

MotifDescription
*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 ​

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%

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.

Motifs utiles ​

MotifDescription
%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

En savoir plus

Documentation complète : syntaxe de chemin GJSON

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.

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.

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 :

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

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

Documentation de Pocket Alert