Saltar al contenido

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ónDescripció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:

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

Configuración de la plantilla ​

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%

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 Murphy

Integraciones habituales ​

Webhooks de GitHub ​

text
🔔 %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):

text
🚨 %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 ​

text
⚠️ %state%: %title%

%message%

Status: %status%

Uptime Robot ​

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

Sintaxis avanzada de rutas ​

Para extraer datos JSON complejos, usamos la sintaxis de rutas GJSON.

Patrones útiles ​

PatrónDescripció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):

  1. El campo level del payload JSON entrante
  2. El default_level del webhook (se define al crear el webhook)
  3. El nivel predeterminado de la aplicación
  4. 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:

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

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:

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

Esto enviará una notificación de prueba a tus dispositivos usando la plantilla de mensajes configurada.

Documentación de Pocket Alert