Ir para o conteúdo

Criar webhook POST ​

Crie um novo webhook para receber notificações push de serviços externos.

Endpoint ​

POST https://api.pocketalert.app/v1/webhooks

Autenticação ​

Obrigatório

Inclua um destes cabeçalhos na sua requisição:

  • Token: <your-api-key> — Obtenha em Chaves de API
  • Authorization: Bearer <jwt-token> — Obtido em Entrar

Requisição ​

Cabeçalhos ​

CabeçalhoObrigatórioDescrição
Token✅Sua chave de API
Authorization✅Bearer <jwt-token>

Parâmetros do corpo ​

ParâmetroTipoObrigatórioDescrição
namestring✅Nome do webhook (ex.: "Sentry", "GitHub")
urlstring❌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
messagestring✅Modelo da mensagem (use * para JSON bruto)
application_idstring❌TID do aplicativo para categorizar as mensagens
device_idstring❌TID do dispositivo de destino (omita para todos os dispositivos)
default_levelstring | 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.
actionsstring❌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):

json
[
  { "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:

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

bash
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"
  }'
javascript
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}`);
python
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']}")
php
$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

CampoTipoDescrição
tidstringIdentificador único do webhook
namestringNome do webhook
urlstringSlug da URL do webhook — use isto nos serviços externos
messagestringModelo da mensagem
actionsstringModelo JSON de botões de ação (vazio se não definido)
is_activebooleanSe o webhook está ativo
json
{
  "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 ​

StatusDescrição
400Requisição inválida — name ou message ausente, default_level inválido ou modelo actions inválido
401Não autorizado — token inválido ou ausente
403Proibido — limite de webhooks do seu plano atingido
404Não encontrado — application_id ou device_id não existe
409Conflito — o slug de url já está em uso

Documentação do Pocket Alert