Webhook falhando

Se seus webhooks estão falhando, este guia cobre os problemas mais comuns em ordem de frequência.

1. Verificar o log de deliveries

Dashboard → Configurações → Webhooks → seu endpoint → Ver deliveries.

O log mostra:

• Status HTTP retornado pelo seu servidor
• Corpo do request enviado
• Resposta do seu servidor
• Próxima tentativa (se em retry)

Identificar o status HTTP é o primeiro passo para o diagnóstico correto.

---

Diagnóstico por status HTTP

200 mas sem processamento

Se o delivery aparece como sucesso mas o seu sistema não processou o evento:

• Verifique se o seu handler está realmente sendo chamado (adicione um log no início da função)
• Confirme que o endpoint recebe POST (não GET)
• Verifique se há middleware de parsing que transforma o body antes do handler

400 — Bad Request

Seu servidor está recusando o formato do payload.

• Confirme que está recebendo Content-Type: application/json
• Se usa express.json(), troque por express.raw() para poder verificar o HMAC antes de parsear:

// Errado para webhooks com HMAC:
app.use(express.json())

// Correto:
app.post('/webhook', express.raw({ type: 'application/json' }), handler)

401 / 403 — Não autorizado

Seu servidor está rejeitando o request.

• Se você tem autenticação própria no endpoint, verifique se o Simple Agent está enviando o header esperado
• Webhooks do Simple Agent não enviam autenticação adicional além da assinatura HMAC — use a verificação HMAC como autenticação

404 — Not Found

A URL do webhook está errada ou o endpoint foi removido.

• Confirme a URL no dashboard — não deve ter trailing slash extra ou path incorreto
• Teste com curl: curl -X POST https://seusite.com/webhook -H "Content-Type: application/json" -d '{}'

500 — Erro no seu servidor

Há um erro não tratado no seu handler.

• Adicione try/catch em volta de todo o processamento
• Retorne 200 imediatamente e processe de forma assíncrona se o processamento for demorado

timeout — Sem resposta em 10s

Seu handler está demorando mais de 10 segundos.

Solução: Retorne 200 imediatamente e processe em background:

app.post('/webhook', async (req, res) => {
  res.status(200).json({ received: true }); // responde imediatamente

  // processa em background (não bloqueia a resposta)
  processEvent(req.body).catch(console.error);
});

---

Assinatura HMAC não valida

Problema mais comum: body foi parsed antes da verificação

A assinatura é calculada sobre o body bruto (string). Se você parsear o JSON antes de verificar, a comparação falha:

// ERRADO - body já é um objeto, não string
const rawBody = JSON.stringify(req.body); // isso NÃO é o mesmo que o body original

// CORRETO - usar o body bruto
app.post('/webhook', express.raw({ type: '*/*' }), (req, res) => {
  const rawBody = req.body.toString(); // string original enviada pelo Simple Agent
  // verificar HMAC com rawBody...
});

Timestamp muito antigo

A verificação padrão rejeita eventos com mais de 5 minutos. Se seu servidor tem o relógio desincronizado:

# Verificar skew do NTP
timedatectl status
ntpq -p

Secret incorreto

Confirme que está usando o Webhook Secret da tela de edição do webhook específico, não a API Key da conta.

---

Testar com curl

Para verificar se o problema é no Simple Agent ou no seu servidor:

# Simula um evento básico sem verificação HMAC
curl -X POST https://seusite.com/webhook \
  -H "Content-Type: application/json" \
  -H "X-Simple Agent-Signature: sha256=test" \
  -H "X-Simple Agent-Timestamp: $(date +%s)" \
  -d '{"event":"test","id":"evt_test","created_at":"2026-05-14T10:00:00Z","agent_id":"ag_test","data":{}}'

Se o seu servidor responder 200, o problema é na assinatura HMAC ou na URL. Se responder erro, o problema é no seu handler.

---

Reenviar eventos manualmente

Para reenviar um evento específico sem esperar o retry automático:

curl -X POST https://simple-agent.me/api/v1/webhooks/wh_xxx/deliveries/del_xxx/retry \
  -H "Authorization: Bearer af_live_xxx"

Ou pelo dashboard: Ver deliveries → ícone de reenvio ao lado do delivery com falha.

Webhooks → · Erros da API → · Widget não carrega →