Alertas via Webhook

Webhooks permitem que o TheAlert envie notificações para qualquer sistema que aceite requisições HTTP POST. Use para integrar com PagerDuty, OpsGenie, sistemas internos, scripts de automação ou qualquer ferramenta customizada.

⚠️

A integração via Webhook requer o plano STARTER ou superior.

Como funciona

Quando um monitor muda de estado, o TheAlert faz um POST para a URL configurada com um payload JSON descrevendo o evento.

Configuração

Acesse "Integrações" no TheAlert
Clique em "+ Nova Integração" → Webhook
Preencha:
- Nome: identificação (ex: PagerDuty, Sistema Interno)
- URL: endpoint que receberá os POSTs
- Secret (opcional): chave para validar assinatura HMAC
Clique em "Salvar"
Clique em "Testar" para enviar um payload de teste

Payload do Webhook

O TheAlert envia um POST com Content-Type: application/json e o seguinte payload:

{
  "monitorName": "API Principal",
  "monitorUrl": "https://api.exemplo.com",
  "status": "DOWN",
  "errorMessage": "connect ETIMEDOUT",
  "timestamp": "2026-03-11T15:00:00.000Z"
}

Campos do payload

Campo	Tipo	Descrição
`monitorName`	string	Nome do monitor conforme configurado
`monitorUrl`	string	URL ou host monitorado
`status`	string	Estado atual: `DOWN`, `UP`, `DEGRADED` ou `FLAPPING`
`errorMessage`	string \| null	Mensagem de erro quando DOWN/DEGRADED; `null` quando UP
`timestamp`	string	Data/hora do evento em ISO 8601 (UTC)

Valores possíveis de `status`

Valor	Significado
`DOWN`	Monitor fora do ar
`UP`	Monitor se recuperou
`DEGRADED`	Monitor degradado (ex: 4xx HTTP)
`FLAPPING`	Monitor oscilando — alertas sendo suprimidos

Validação de assinatura (HMAC-SHA256)

Se você configurou um secret, o TheAlert inclui um header de assinatura em cada requisição:

X-TheAlert-Signature: sha256=abc123def456...

A assinatura é calculada como HMAC-SHA256 do body JSON usando o secret configurado.

Como validar em Node.js

const crypto = require('crypto')
 
function validateSignature(body, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex')
 
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}
 
// Express.js middleware
app.post('/webhook/thealert', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-thealert-signature']
  const isValid = validateSignature(req.body, signature, process.env.WEBHOOK_SECRET)
 
  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' })
  }
 
  const payload = JSON.parse(req.body)
  console.log(`Monitor ${payload.monitorName} is ${payload.status}`)
 
  res.json({ ok: true })
})

Como validar em Python

import hmac
import hashlib
 
def validate_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Use sempre timingSafeEqual (Node.js) ou hmac.compare_digest (Python) para comparar assinaturas. Comparação simples com == é vulnerável a timing attacks.

Exemplos de integração

PagerDuty (via Events API v2)

Você pode criar um script simples que recebe o webhook do TheAlert e envia para o PagerDuty:

app.post('/webhook/thealert', async (req, res) => {
  const { monitorName, status, errorMessage } = req.body
 
  if (status === 'DOWN') {
    await fetch('https://events.pagerduty.com/v2/enqueue', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        routing_key: process.env.PAGERDUTY_KEY,
        event_action: 'trigger',
        payload: {
          summary: `${monitorName} está DOWN`,
          source: 'TheAlert',
          severity: 'critical',
          custom_details: { error: errorMessage }
        }
      })
    })
  }
 
  res.json({ ok: true })
})

Script de restart automático

#!/bin/bash
# Recebe webhook via ngrok ou servidor público
 
# Lê o payload
PAYLOAD=$(cat)
STATUS=$(echo $PAYLOAD | jq -r '.status')
MONITOR=$(echo $PAYLOAD | jq -r '.monitorName')
 
if [ "$STATUS" = "DOWN" ] && [ "$MONITOR" = "API Principal" ]; then
    systemctl restart minha-api
    echo "API reiniciada após detecção de DOWN"
fi

Slack customizado (sem usar a integração nativa)

app.post('/webhook/thealert', async (req, res) => {
  const { monitorName, status, errorMessage, monitorUrl } = req.body
  const emoji = status === 'UP' ? '🟢' : '🔴'
 
  await fetch(process.env.SLACK_WEBHOOK_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      text: `${emoji} *${monitorName}* está *${status}*\n${errorMessage || ''}`
    })
  })
 
  res.json({ ok: true })
})

Requisitos do endpoint

O endpoint que recebe o webhook deve:

Aceitar requisições POST
Ser acessível publicamente na internet
Retornar um status HTTP 2xx em até 10 segundos
Estar disponível via HTTPS (recomendado)

⚠️

Se o endpoint retornar erro (4xx ou 5xx) ou não responder em 10 segundos, o TheAlert registra a tentativa como falha. Isso não interfere nos alertas via outros canais.

Planos

Plano	Webhooks disponíveis
FREE	Não
STARTER	Sim
PRO	Sim
BUSINESS	Sim

Próximos passos

Telegram Criar Status Page