Configuración de webhooks
Aprende a configurar las plantillas de mensajes de los webhooks para extraer datos de los payloads JSON entrantes.
Sintaxis de la plantilla de mensajes
Al crear un webhook, defines una plantilla de mensaje que determina cómo se formatean los datos JSON entrantes en notificaciones.
Patrones básicos
| Patrón | Descripción |
|---|---|
* | Muestra el payload JSON completo |
%field% | Extrae un campo de primer nivel |
%object.field% | Extrae un campo anidado |
%array.0% | Obtiene el primer elemento de un array |
%array.0.field% | Obtiene un campo de un elemento del array |
%% | Un % literal. Solo es necesario justo antes de una palabra seguida de otro %, como en %cpu%%%; un % seguido de un espacio, como en 90% on %host%, se mantiene tal cual |
Un marcador de posición nunca contiene espacios, así que los signos de porcentaje en el texto normal no se modifican: CPU over 90% on %host% se muestra como CPU over 90% on db-1.
Ejemplos
Payload JSON de ejemplo
Considera este payload 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"]}
]
}
}Configuración de la plantilla
*Title: %event.title%
Message: %event.message%
Tags: %event.tags%
Users: %event.users.0%
First user: %event.users.0.first% %event.users.0.last%Resultado
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 MurphyIntegraciones habituales
Webhooks de GitHub
🔔 %action%: %repository.full_name%
%sender.login%: %commits.0.message%Seguimiento de errores con Sentry
Para una integración interna usada como acción de alerta (alertas de incidencias):
🚨 %data.event.title%
%data.event.culprit%
Rule: %data.triggered_rule%Añade un botón view con %data.event.web_url% para abrir la incidencia. El plugin Webhooks heredado envía un payload distinto: en ese caso, usa %project_name%: %event.title% y %url%.
Alertas de Grafana
⚠️ %state%: %title%
%message%
Status: %status%Uptime Robot
🔴 %monitorFriendlyName%
Status: %alertTypeFriendlyName%
Details: %alertDetails%Sintaxis avanzada de rutas
Para extraer datos JSON complejos, usamos la sintaxis de rutas GJSON.
Patrones útiles
| Patrón | Descripción |
|---|---|
%users.#% | Número de elementos del array |
%users.#.first% | Array con todos los valores de first |
%users.@reverse% | Invierte el orden del array |
%data.@pretty% | Muestra el JSON con formato legible |
Más información
Documentación completa: sintaxis de rutas GJSON
Nivel de prioridad
Los payloads entrantes pueden incluir un campo level para controlar cómo se entrega la notificación push: un nombre (silent, low, default, high, critical) o un entero (-2..2). Consulta Niveles de prioridad de los mensajes.
Orden de resolución (gana la primera coincidencia):
- El campo
leveldel payload JSON entrante - El
default_leveldel webhook (se define al crear el webhook) - El nivel predeterminado de la aplicación
default(normal)
A diferencia de la API directa, la entrada de los webhooks es tolerante: un valor level no reconocido se ignora (se usan los valores predeterminados) en lugar de rechazarse, así que las alertas nunca se pierden.
Botones de acción
Un webhook puede añadir hasta 3 botones de acción a cada notificación que genera. Define el campo actions (una cadena JSON) al crear o actualizar el webhook; consulta Crear webhook → Plantilla de botones de acción.
label y value admiten los mismos marcadores %field.path% que la plantilla de mensajes, así que los botones se pueden construir a partir del payload 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\"}" }
]Tras la sustitución, cada botón se valida (type ∈ view/http/copy; view y http necesitan una URL http(s)). Igual que con el análisis del nivel, esto es tolerante: un botón no válido se descarta por sí solo, y los demás botones y la notificación se entregan igualmente.
Los botones de acción son una función de pago. En los planes gratuitos se eliminan y la notificación se entrega sin ellos.
Después de crear un webhook, puedes probarlo:
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',
],
]);Esto enviará una notificación de prueba a tus dispositivos usando la plantilla de mensajes configurada.