Criar webhook POST
Crie um novo webhook para receber notificações push de serviços externos.
Endpoint
POST https://api.pocketalert.app/v1/webhooksAutenticação
Obrigatório
Inclua um destes cabeçalhos na sua requisição:
Token: <your-api-key>— Obtenha em Chaves de APIAuthorization: Bearer <jwt-token>— Obtido em Entrar
Requisição
Cabeçalhos
| Cabeçalho | Obrigatório | Descrição |
|---|---|---|
Token | ✅ | Sua chave de API |
Authorization | ✅ | Bearer <jwt-token> |
Parâmetros do corpo
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | ✅ | Nome do webhook (ex.: "Sentry", "GitHub") |
url | string | ❌ | Slug da URL de recebimento https://p4a.me/wh/{url}. Um slug aleatório de 20 caracteres é gerado quando omitido. Precisa ser único: um slug já em uso retorna 409 |
message | string | ✅ | Modelo da mensagem (use * para JSON bruto) |
application_id | string | ❌ | TID do aplicativo para categorizar as mensagens |
device_id | string | ❌ | TID do dispositivo de destino (omita para todos os dispositivos) |
default_level | string | int | ❌ | Nível de prioridade padrão aplicado às mensagens deste webhook quando o payload não especifica um: um nome (silent, low, default, high, critical) ou um int (-2..2). Veja Níveis de prioridade da mensagem. |
actions | string | ❌ | Modelo JSON de botões de ação. Mesmo formato de ações da mensagem, mas label/value podem conter marcadores %field.path% resolvidos com base no payload recebido. Armazenado como string JSON. Recurso pago: removido nos planos gratuitos. |
Modelo de botões de ação
actions permite que as notificações geradas pelo webhook tragam até 3 botões, com marcadores %field.path% substituídos pelos dados do payload recebido (mesma sintaxe do modelo de mensagem):
[
{ "type": "view", "label": "Open issue", "value": "%issue.html_url%" },
{ "type": "http", "label": "Ack", "value": "{\"url\":\"https://ops.example.com/ack/%issue.id%\",\"method\":\"POST\"}" }
]O modelo é verificado quando você o salva: deve ser um array JSON com no máximo 3 botões, com um type válido, e um botão sem marcadores precisa ser totalmente válido, ou a requisição retorna 400.
Depois da substituição, cada botão é validado como as ações da mensagem. Um botão que fique inválido para este payload, como um botão view cujo campo de URL está ausente, é descartado sozinho; os outros botões e a mensagem continuam sendo entregues.
Botões de ação são um recurso pago. Nos planos gratuitos, eles são removidos no servidor e a mensagem é entregue sem eles.
Sintaxe do modelo de mensagem
Use %field.path% para extrair valores do JSON recebido:
| Modelo | Descrição |
|---|---|
* | Exibe o payload JSON inteiro |
%field% | Extrai um campo de primeiro nível |
%object.field% | Extrai um campo aninhado |
%array.0.field% | Extrai de um array pelo índice |
%% | 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á |
Veja Configurações do webhook para exemplos detalhados.
Exemplo de requisição
curl -X POST "https://api.pocketalert.app/v1/webhooks" \
-H "Token: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"name": "GitHub Push",
"message": "Push to %repository.name%: %head_commit.message%",
"application_id": "s9h1ekk5xb46jikthl"
}'const response = await fetch('https://api.pocketalert.app/v1/webhooks', {
method: 'POST',
headers: {
'Token': 'your-api-key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: 'GitHub Push',
message: 'Push to %repository.name%: %head_commit.message%',
application_id: 's9h1ekk5xb46jikthl'
})
});
const webhook = await response.json();
console.log('Webhook URL:', `https://p4a.me/wh/${webhook.url}`);import requests
response = requests.post(
'https://api.pocketalert.app/v1/webhooks',
headers={'Token': 'your-api-key'},
json={
'name': 'GitHub Push',
'message': 'Push to %repository.name%: %head_commit.message%',
'application_id': 's9h1ekk5xb46jikthl'
}
)
webhook = response.json()
print(f"Webhook URL: https://p4a.me/wh/{webhook['url']}")$response = Http::withHeaders([
'Token' => 'your-api-key',
])->post('https://api.pocketalert.app/v1/webhooks', [
'name' => 'GitHub Push',
'message' => 'Push to %repository.name%: %head_commit.message%',
'application_id' => 's9h1ekk5xb46jikthl',
]);
$webhook = $response->json();
echo 'Webhook URL: https://p4a.me/wh/'.$webhook['url'];Resposta
Resposta de sucesso
201 Created
Webhook criado com sucesso
| Campo | Tipo | Descrição |
|---|---|---|
tid | string | Identificador único do webhook |
name | string | Nome do webhook |
url | string | Slug da URL do webhook — use isto nos serviços externos |
message | string | Modelo da mensagem |
actions | string | Modelo JSON de botões de ação (vazio se não definido) |
is_active | boolean | Se o webhook está ativo |
{
"tid": "kblf7mh9j8jjyeh4fx",
"name": "GitHub Push",
"url": "cs994rqfkk8ljngt",
"message": "Push to %repository.name%: %head_commit.message%",
"actions": "",
"application_tid": "qm47b9pzxzx7applfd0",
"device_tid": "",
"is_active": true,
"created_at": "01.09.2023 22:38:48"
}Usando seu webhook
Configure seu serviço externo para enviar um POST para:
https://p4a.me/wh/{url}Respostas de erro
| Status | Descrição |
|---|---|
400 | Requisição inválida — name ou message ausente, default_level inválido ou modelo actions inválido |
401 | Não autorizado — token inválido ou ausente |
403 | Proibido — limite de webhooks do seu plano atingido |
404 | Não encontrado — application_id ou device_id não existe |
409 | Conflito — o slug de url já está em uso |