Webhooks e notificações: guia prático

Como funcionam os webhooks

Ao criar uma varredura agendada, você pode configurar uma URL de webhook. Quando a varredura completar, o SAFETAGGY envia um POST para essa URL com os resultados. Para detalhes sobre o formato do payload, veja a página de referência de webhooks.

• O webhook é disparado apenas quando a varredura atinge o status completed
• O payload é enviado via POST com Content-Type application/json
• URLs de webhook são validadas contra SSRF (IPs privados e localhost são bloqueados)

Formato do payload

O payload enviado ao seu webhook contém os dados essenciais da varredura:

{
  "event": "scan.completed",
  "scanId": "cm3abc123...",
  "targetUrl": "https://exemplo.com.br",
  "overallScore": 72,
  "findings": {
    "critical": 1,
    "high": 3,
    "medium": 5,
    "low": 2
  },
  "completedAt": "2026-03-16T14:30:00Z"
}

Exemplo: handler em Node.js/Express

Um servidor simples que recebe webhooks do SAFETAGGY e processa os resultados:

const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhook/safetaggy', (req, res) => {
  const { event, scanId, targetUrl, overallScore, findings } = req.body;

  if (event !== 'scan.completed') {
    return res.status(200).json({ ignored: true });
  }

  console.log(`Varredura concluída: ${targetUrl}`);
  console.log(`Score: ${overallScore}/100`);
  console.log(`Achados: ${findings.critical} críticos, ${findings.high} altos`);

  // Salvar no banco, enviar alerta, etc.
  if (overallScore < 70) {
    notificarEquipe(scanId, overallScore);
  }

  res.status(200).json({ received: true });
});

app.listen(3001, () => {
  console.log('Webhook listener rodando na porta 3001');
});

Integração com Slack

O SAFETAGGY suporta webhooks do Slack nativamente. Basta colar a URL do Incoming Webhook do Slack ao criar o agendamento. Para configurar manualmente, você também pode criar um proxy que encaminha para o Slack:

const axios = require('axios');

const SLACK_WEBHOOK_URL = process.env.SLACK_WEBHOOK_URL;

app.post('/webhook/safetaggy', async (req, res) => {
  const { targetUrl, overallScore, findings } = req.body;

  const emoji = overallScore >= 80 ? ':white_check_mark:'
    : overallScore >= 60 ? ':warning:'
    : ':rotating_light:';

  await axios.post(SLACK_WEBHOOK_URL, {
    text: [
      `${emoji} *SAFETAGGY — Varredura concluída*`,
      `*URL:* ${targetUrl}`,
      `*Score:* ${overallScore}/100`,
      `*Achados:* ${findings.critical} críticos, ${findings.high} altos, ${findings.medium} médios`,
      `<https://www.safetaggy.com.br/scan/${req.body.scanId}|Ver relatório completo>`,
    ].join('\n'),
  });

  res.status(200).json({ sent: true });
});

Tratamento de erros e retries

Ao implementar seu webhook handler, considere os seguintes cenários:

Boas práticas para robustez do seu handler:

app.post('/webhook/safetaggy', async (req, res) => {
  // 1. Responda rapido
  res.status(200).json({ received: true });

  // 2. Processe de forma assincrona
  try {
    await processarResultado(req.body);
  } catch (error) {
    console.error('Erro ao processar webhook:', error);
    // Salvar para reprocessamento manual
    await salvarWebhookFalho(req.body, error);
  }
});

Combinando com varreduras agendadas

O cenário mais poderoso é combinar webhooks com varreduras agendadas. Configure uma varredura diária e receba alertas automáticos quando o score mudar:

• Crie um agendamento em Scans → Agendamentos
• Defina a frequência (diário, semanal ou mensal)
• Cole a URL do seu webhook ou do Slack
• O SAFETAGGY dispara a varredura e envia o resultado automaticamente

Para mais detalhes sobre agendamentos e limites por plano, veja a documentação de agendamentos e webhooks.