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 :
{
"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
*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 MurphyIntégrations courantes
Webhooks GitHub
🔔 %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) :
🚨 %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
⚠️ %state%: %title%
%message%
Status: %status%Uptime Robot
🔴 %monitorFriendlyName%
Status: %alertTypeFriendlyName%
Details: %alertDetails%Syntaxe de chemin avancée
Pour l’extraction JSON complexe, nous utilisons la syntaxe de chemin GJSON.
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 |
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) :
- Le champ
levelde la charge utile JSON entrante - Le
default_leveldu webhook (défini lors de la création du webhook) - Le niveau par défaut de l’application
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 :
[
{ "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 -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',
],
]);Cela enverra une notification de test à vos appareils en utilisant le modèle de message configuré.