# Configurações de webhook

Aprenda a configurar templates de mensagem de webhook para extrair dados de payloads JSON recebidos.

## Sintaxe do template de mensagem

Ao criar um webhook, você define um template de mensagem que determina como os dados JSON recebidos são formatados em notificações push.

### Padrões básicos

| Padrão | Descrição |
|---------|-------------|
| `*` | Exibe o payload JSON inteiro |
| `%field%` | Extrai um campo de primeiro nível |
| `%object.field%` | Extrai um campo aninhado |
| `%array.0%` | Obtém o primeiro elemento de um array |
| `%array.0.field%` | Obtém um campo de um elemento do array |
| `%%` | Um `%` literal. Só é necessário logo antes de uma palavra seguida de outro `%`, como em `%cpu%%%`; um `%` seguido de espaço, como em `90% on %host%`, permanece como está |

Um placeholder nunca contém espaços, então os sinais de porcentagem em texto comum não são alterados: `CPU over 90% on %host%` vira `CPU over 90% on db-1`.

## Exemplos

### Payload JSON de exemplo

Considere este payload de webhook recebido:

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

### Configuração do template

**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 da saída

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

## Integrações comuns

### Webhooks do GitHub

```text
🔔 %action%: %repository.full_name%
%sender.login%: %commits.0.message%
```

### Rastreamento de erros com Sentry

Para uma integração interna usada como ação de alerta (alertas de issues):

```text
🚨 %data.event.title%
%data.event.culprit%
Rule: %data.triggered_rule%
```

Adicione um botão `view` com `%data.event.web_url%` para abrir a issue. O plugin Webhooks legado envia um payload diferente: nele, use `%project_name%: %event.title%` e `%url%`.

### Alertas do Grafana

```text
⚠️ %state%: %title%

%message%

Status: %status%
```

### Uptime Robot

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

## Sintaxe avançada de caminho

Para extração complexa de JSON, usamos a [GJSON Path Syntax](https://github.com/tidwall/gjson/blob/master/SYNTAX.md).

### Padrões úteis

| Padrão | Descrição |
|---------|-------------|
| `%users.#%` | Quantidade de itens do array |
| `%users.#.first%` | Array com todos os valores de `first` |
| `%users.@reverse%` | Inverte a ordem do array |
| `%data.@pretty%` | Formata o JSON com indentação |

> **Tip: Saiba mais**
>
> Documentação completa: [GJSON Path Syntax](https://github.com/tidwall/gjson/blob/master/SYNTAX.md)

## Nível de prioridade

Payloads recebidos podem trazer um campo `level` para controlar como a notificação push é entregue — um nome (`silent`, `low`, `default`, `high`, `critical`) ou um inteiro (`-2`..`2`). Veja [Níveis de prioridade de mensagem](https://info.pocketalert.app/api/messages/create.md#priority-levels).

Ordem de resolução (vence a primeira correspondência):

1. O campo `level` no payload JSON recebido
2. O `default_level` do webhook (definido ao criar o webhook)
3. O nível padrão do aplicativo
4. `default` (normal)

Diferente da API direta, a entrada de webhooks é tolerante: um valor `level` não reconhecido é ignorado (usando os padrões) em vez de rejeitado, para que alertas nunca sejam descartados.

## Botões de ação

Um webhook pode anexar até 3 botões de ação a cada notificação que gera. Defina o campo `actions` (uma string JSON) ao criar ou atualizar o webhook — veja [Criar webhook → Template de botões de ação](https://info.pocketalert.app/api/webhooks/create.md#action-buttons-template).

`label` e `value` aceitam os mesmos placeholders `%field.path%` do template de mensagem, então os botões podem ser montados a partir do payload recebido:

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

Após a substituição, cada botão é validado (`type` ∈ `view`/`http`/`copy`; `view` e `http` precisam de uma URL `http(s)`). Assim como na análise de level, isso é tolerante: um botão inválido é descartado sozinho, e os outros botões e a notificação continuam sendo entregues.

Botões de ação são um recurso pago. Em planos gratuitos, eles são removidos e a notificação é entregue sem eles.

Depois de criar um webhook, você pode testá-lo:

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

Isso enviará uma notificação de teste para seus dispositivos usando o template de mensagem configurado.
