Ir para o conteúdo

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ãoDescriçã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 ​

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

Padrões úteis ​

PadrãoDescriçã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

Saiba mais

Documentação completa: GJSON Path Syntax

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.

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.

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:

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

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

Documentação do Pocket Alert