Webhooks de alertas

Webhooks de alerta entregam, em endpoints HTTP do cliente, os mesmos eventos que o Publitik envia por email, push ou notificação in-app. Permitem integrar o sinal do mercado editorial diretamente em sistemas internos, dashboards ou ferramentas de automação.

Disponibilidade: webhooks de saída são exclusivos do tier Enterprise. Demais canais (email, push, in-app) estão disponíveis em todos os planos.

Para quem é

• Times de TI que querem rotear alertas para ferramentas internas (Slack, Teams, dashboards de BI).
• Operações comerciais e editoriais que automatizam reações a eventos (criar tarefa, abrir card, disparar campanha).
• Agências e consultorias que entregam relatórios contínuos a clientes finais.

Como funciona

1. Você cria uma regra de notificação dentro do app — define o critério (autor, livro, ranking, categoria) e marca "Webhook" como canal de entrega, informando a URL do endpoint.
2. Quando um item novo casa com a regra, geramos uma notificação e enfileiramos uma entrega para o webhook.
3. Um worker dedicado faz POST JSON na URL configurada, com retentativas automáticas se necessário.
4. O status da entrega (sent, failed, skipped) fica visível no histórico de notificações dentro do app.

1. Configurar uma regra

Dentro do app, vá em Conta → Notificações → Regras e clique em "Nova regra". Defina os filtros, marque "Webhook" e cole a URL do receiver. A URL deve aceitar POST com Content-Type: application/json.

2. Payload do webhook

O corpo da requisição é um JSON com o seguinte formato:

{
  "source": "publitik",
  "notification_id": "ckxa3b9e0001qjs0g8h2ydp1m",
  "rule_id": "ckxa3b9d0000zjs0g7n8r4wv6",
  "rule_name": "Mencao a Itamar Vieira Junior",
  "title": "Itamar Vieira Junior reentra no top 10 da Veja",
  "body": "O autor de Torto Arado aparece na 8a posicao do ranking semanal de ficcao da Veja, com forte alta apos entrevista no Roda Viva.",
  "link": "https://app.publitik.com/dashboard/itens/cm9z1y8b3000abcd",
  "timestamp": "2026-05-15T18:42:11.327Z",
  "text": "*Itamar Vieira Junior reentra no top 10 da Veja*\nO autor de Torto Arado aparece na 8a posicao...\nhttps://app.publitik.com/...",
  "blocks": [
    {
      "type": "section",
      "text": { "type": "mrkdwn", "text": "*Itamar Vieira Junior...*" }
    },
    {
      "type": "section",
      "text": { "type": "mrkdwn", "text": "<https://app.publitik.com/...|Ver no Publitik>" }
    }
  ]
}

Campos

Campo	Tipo	Descrição
source	string	Sempre "publitik". Útil para distinguir entre múltiplas integrações no mesmo receiver.
notification_id	string	ID único da notificação. Idempotente — pode aparecer mais de uma vez se houve retentativa.
rule_id	string	ID da regra que disparou.
rule_name	string	Nome legível da regra, como configurado pelo usuário.
title	string	Título curto do evento.
body	string	Resumo em texto plano (1 a 3 frases).
link	string (URL)	URL absoluta para o item no app Publitik. Login necessário.
timestamp	string (ISO 8601 UTC)	Quando a notificação foi gerada (não quando foi entregue).
text	string	Versão Slack/Discord-friendly (markdown plano com link).
blocks	array	Bloco no formato Slack Block Kit, renderizado nativamente por Slack e Discord.

O payload foi desenhado para servir tanto receivers genéricos (Zapier, n8n, endpoint próprio) quanto Slack/Discord nativos sem transformação intermediária. Ignore os campos que não usar.

3. Headers e método

• POST na URL configurada
• Content-Type: application/json
• Sem custom headers de autenticação (veja Segurança)
• Resposta esperada: qualquer status 2xx = sucesso. 3xx, 4xx, 5xx = falha (entra em retentativa).

4. Retentativas e timeout

• Timeout: 8 segundos. Se o receiver não responder nesse prazo, a tentativa é considerada falha.
• Retentativas: até 3 tentativas por entrega.
• Backoff exponencial entre tentativas: ~10s, depois ~20s, depois ~40s.
• Após esgotar as retentativas, a entrega fica marcada como FAILED com o último erro registrado. Não há reentrega automática após esse ponto — o evento continua visível no histórico do app, mas não tenta de novo.

5. Segurança

Recomendações para proteger o endpoint:

• Token na URL (recomendado hoje): use uma URL com caminho ou query secreta — https://exemplo.com/hooks/publitik/<token-aleatorio>. O receiver valida o token antes de processar. A URL fica armazenada criptografada no nosso lado e nunca aparece em logs ou UI.
• Whitelist de IP: as entregas saem do IP fixo da nossa VPS. Solicite o IP a help@publitik.com.
• HTTPS obrigatório em produção. URLs http:// são aceitas apenas para testes locais (loopback ou domínio interno).
• HMAC signature: ainda não está implementado. Se o seu padrão interno exigir, use token na URL como substituto e nos avise — está em backlog.

6. Exemplos de receivers

Slack

Crie um Incoming Webhook no app Slack e cole a URL na regra. O Slack renderiza nativamente os campos text e blocks do payload — não precisa fazer nada do lado do Slack.

Discord

Crie um webhook no canal Discord (Configurações → Integrações → Webhooks → Novo Webhook). Adicione ?wait=true no final da URL para receber confirmação. O Discord renderiza text como mensagem.

Zapier / n8n / Make

Use o trigger Webhooks by Zapier (ou equivalente) para capturar o JSON. Os campos chegam estruturados — encaminhe para qualquer serviço (Notion, Airtable, Asana, etc).

Endpoint próprio

Exemplo mínimo em Node.js (Express):

app.post("/hooks/publitik/:token", express.json(), (req, res) => {
  if (req.params.token !== process.env.PUBLITIK_HOOK_TOKEN) {
    return res.status(401).end();
  }
  const { title, body, link, rule_name } = req.body;
  // ... seu processamento aqui ...
  res.status(200).end();
});

Exemplo em Python (FastAPI):

@app.post("/hooks/publitik/{token}")
async def publitik_hook(token: str, payload: dict):
    if token != os.getenv("PUBLITIK_HOOK_TOKEN"):
        raise HTTPException(status_code=401)
    # ... seu processamento aqui ...
    return {"ok": True}

7. Troubleshooting

• Status SKIPPED com "tier não-Enterprise": a conta caiu de Enterprise para Pro depois que a regra foi criada. A regra continua válida para os outros canais; o webhook volta automaticamente ao reativar Enterprise.
• Status FAILED com timeout: seu receiver levou mais de 8s para responder. Reduza o trabalho síncrono — confirme com 200 imediatamente e processe em fila.
• Status FAILED com HTTP 4xx: token errado, URL inválida ou payload rejeitado. Cheque os logs do receiver.
• Recebi o mesmo evento duas vezes: efeito esperado em retentativa. Use notification_id como chave de idempotência no seu lado.
• Não estou recebendo nada: confirme que (a) a regra tem "Webhook" ativo como canal, (b) o tier é Enterprise, (c) há itens novos casando com a regra (aparecem em Notificações in-app). Se sim, abra suporte com o rule_id.