# 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:

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

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

### 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](https://github.com/tidwall/gjson/blob/master/SYNTAX.md).

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

> **Tip: Más información**
>
> Documentación completa: [sintaxis de rutas GJSON](https://github.com/tidwall/gjson/blob/master/SYNTAX.md)

## 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](https://info.pocketalert.app/api/messages/create.md#priority-levels).

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](https://info.pocketalert.app/api/webhooks/create.md#action-buttons-template).

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

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

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