Referência da API

Um único endpoint, um único pedido POST. Envie JSON para o URL de webhook do seu canal e nós tratamos das notificações, da formatação e da entrega.

Enviar um alerta

Dispare um novo alerta num canal específico. Este é o endpoint principal para enviar notificações a partir da sua app.

POSThttps://zenhook.dev/api/webhook/{token}
Exemplo de pedido
curl -X POST https://zenhook.dev/api/webhook/abc123def456 \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New signup",
    "level": "success",
    "emoji": "🎉",
    "source": "My App",
    "actor": {
      "id": "42",
      "name": "Jane Doe",
      "email": "[email protected]",
      "plan": "Pro"
    },
    "linkUrl": "https://myapp.com/admin/users/42",
    "linkText": "View Profile"
  }'

Parâmetros de caminho

tokenstringObrigatório
O token de webhook único do seu canal. Encontra-o nas definições do canal.

Corpo do pedido

titlestringObrigatório
Um resumo curto do alerta. Usado como título nas notificações. No máximo 200 caracteres.
levelenum
Nível de gravidade do alerta: info, success, warning, error. Padrão info.
messagestring
Texto detalhado. No máximo 5000 caracteres.
emojistring
Emoji apresentado ao lado do título. Aceita um carácter unicode ("🚀"), um nome ("rocket") ou um shortcode (":rocket:"). Os nomes e os shortcodes são convertidos na receção. Os nomes desconhecidos são ignorados em vez de aparecerem como texto literal. Nomes reconhecidos: rocket · siren · warning · check · cross · fire · bug · zap · bell · tada · sparkles · envelope · chat · phone · megaphone · wave · eyes · heart · thumbsup · office · door · house · factory · lock · unlock · key · link · package · gear · wrench · shield · money · chart · clock · hourglass · flag · star · target · pin · tag · computer · server · database · cloud · bulb · gem · anchor · pick · bank.
actorobject
Sobre quem é o alerta. Aparece como autor do alerta e também na notificação push e no assunto do e-mail: “Novo registo” chega finalmente com um nome. Envie { name, email, id, plan, company, location, avatarUrl, url }, parte disso, ou apenas uma string. user também é aceite. Só com o e-mail, o Zenhook deduz o nome apresentado, as iniciais, a empresa por trás de um domínio profissional e o Gravatar, se a pessoa tiver um.
fieldsarray
Objetos chave-valor para dados estruturados. Cada objeto tem label e value.name é aceite em vez de label, e um valor pode ser um número ou um booleano.
linkUrlstring
URL de um link de ação clicável, apresentado por baixo do título.
linkTextstring
Texto do botão do link. Padrão "View" quando linkUrl está definido.
sourcestring
Nome do autor apresentado no cabeçalho do alerta (por exemplo "GitHub", "Stripe"). Padrão "Webhook".
metadataobject
Objeto JSON livre apresentado numa secção expansível "Raw Payload", com cópia para a área de transferência. No máximo 10 KB.
Erros

Os erros são documentos RFC 9457, servidos como application/problem+json. Decida com base emtype e mostre title. O antigo campo error continua presente, para que as integrações escritas antes continuem a funcionar.

json
{
  "type": "https://zenhook.dev/problems/unknown-token",
  "title": "Invalid webhook token",
  "status": 404,
  "error": "Invalid webhook token"
}
Idempotency-Key

Envie um cabeçalho Idempotency-Key e um reenvio da mesmo pedido devolve a primeira resposta em vez de criar um segundo alerta, durante 24 h. A repetição traz Idempotency-Replayed: true. Um reenvio enquanto o primeiro pedido ainda está em curso recebe um 409 em vez de um duplicado. Use-o em tudo o que volta a tentar depois de um tempo limite, a começar pelos scripts de deploy.

Respostas

201 Created

Alerta recebido e colocado na fila para entrega.destination informa o espaço de trabalho e o canal do token, para que uma integração ligada no sítio errado apareça na resposta, e não dias depois, no canal errado.

json
{
  "success": true,
  "alertId": "clx1234567890abcdef",
  "destination": {
    "workspace": { "id": "ws_...", "name": "Acme Corp" },
    "channel": { "id": "ch_...", "name": "deploys", "slug": "deploys" }
  }
}

Use https://zenhook.dev/api/ nas integrações. O alias da API com www também aceita pedidos sem redirecionamento. Se um webhook ou heartbeat de monitor ultrapassar o limite de pedidos, a resposta 429 inclui Retry-After: espere esse número de segundos antes de tentar novamente. A quota mensal de eventos é independente; esperar um minuto não a renova.

Notificações de workflow

Um deploy ou uma release é um único processo, não cinco alertas. Adicione um blocoworkflow e cada POST com o mesmorunId atualiza um único alerta: o cartão mostra cada etapa em direto e o feed nunca se enche de ruído intermédio.

bash
# every POST of a run carries the same runId
curl -X POST https://zenhook.dev/api/webhook/YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "title": "myapp deploy",
    "workflow": {
      "runId": "myapp-20260722-1015",
      "state": "running",
      "steps": [
        { "name": "test",   "state": "done",    "seconds": 46, "info": "716 tests" },
        { "name": "build",  "state": "running" },
        { "name": "deploy", "state": "pending" }
      ]
    }
  }'

Estados: a execução é running, passed ou failed; cada etapa é pending, running, done, failed ou skipped. Envie a lista COMPLETA de etapas toda vez; o servidor substitui, nunca mescla.

Política de notificação: o primeiro POST notifica (iniciado), as atualizações em andamento são silenciosas, e o estado final notifica uma vez e traz o alerta de volta como não lido. O nível vem do estado: uma execução com falha nunca pode dizer que passou.

Faturação: um processo é um único evento, contado no primeiro POST. As atualizações são grátis.

Em caso de falha: envie workflow.error com o final do log; ele aparece no cartão para si diagnosticar pelo telemóvel.

Dados estruturados

Use a lista fields para incluir metadados ricos, exibidos no painel e nos alertas por e-mail.

Exemplo com fields
{
  "title": "Build Failed",
  "level": "error",
  "fields": [
    { "label": "Branch", "value": "main" },
    { "label": "Commit", "value": "abc123f" },
    { "label": "Author", "value": "John Smith" },
    { "label": "Error", "value": "npm install timed out after 300s" }
  ],
  "linkUrl": "https://github.com/org/repo/actions/runs/123",
  "linkText": "View Logs"
}

Widgets no feed

Nada a configurar. O Zenhook lê cada tipo de evento a partir do histórico e desenha o widget que lhe corresponde. Um tipo de evento é um fluxo: mesmo canal e mesmo título, números ignorados, por isso Pedido 1284 pago ePedido 1285 pago formam um só fluxo. Mantenha o título estável e coloque o que muda em message, fields ouactor.

  • Contador, por predefinição: qualquer fluxo que se repete. O número do dia, a diferença para ontem à mesma hora, barras por hora. Nada a enviar.
  • Pipeline: um título com deploy, build, release, pipeline ou CI, ou um bloco workflow. As últimas execuções e a taxa de sucesso. Envie level: "error" quando uma execução falhar.
  • Erro: level: "error". Quantas vezes hoje, desde quando, a mensagem e o seu link.
  • Dinheiro: um campo chamado Valor, Preço, Total, Receita ou Pagamento, por exemplo 49,00 €. O total do dia.
  • Pessoa: um actor (ou user). Quem, e quantos hoje e esta semana.
  • Sequência: um evento mais ou menos diário, como uma sincronização ou um backup. O número de dias seguidos.
  • Um evento isolado continua a ser um cartão, com tudo visível. Abra um widget para ler os seus eventos.
bash
curl -X POST https://zenhook.dev/api/webhook/YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Pagamento recebido",
    "level": "success",
    "actor": "[email protected]",
    "fields": [{ "label": "Valor", "value": "49,00 €" }]
  }'
Ver cada tipo, tal como aparece →

Ler os alertas

O endpoint de webhook acima é público e só de escrita: qualquer pessoa com o token do canal pode publicar nele. Para listar os alertas, marcá-los como lidos ou criar uma integração que os consuma, use a API de leitura autenticada com um token Bearer.

Primeiros passos