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:
{
"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
*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 MurphyIntegrações comuns
Webhooks do GitHub
🔔 %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):
🚨 %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
⚠️ %state%: %title%
%message%
Status: %status%Uptime Robot
🔴 %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ã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 |
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):
- O campo
levelno payload JSON recebido - O
default_leveldo webhook (definido ao criar o webhook) - O nível padrão do aplicativo
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:
[
{ "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 -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',
],
]);Isso enviará uma notificação de teste para seus dispositivos usando o template de mensagem configurado.