Solução de problemas
Webhook não chega
O que conferir quando os eventos não chegam ao seu endpoint.
Cada sintoma abaixo segue o mesmo formato: o que você vê, a causa e o que fazer.
Comece por um teste
Seção intitulada “Comece por um teste”Mande um evento destination.test ao destino e veja o resultado. No painel, abra as entregas do destino: cada tentativa guarda o status e os primeiros 1024 bytes da sua resposta.
curl -X POST https://api.messajo.com/v1/destinations/$DESTINATION_ID/test \ -H "Authorization: Bearer $MESSAJO_API_KEY"import { Messajo } from "@messajo/sdk";
const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY });
await messajo.destinations.test(destinationId);O teste vai só para esse destino, numa tentativa única, mesmo com ele pausado.
Nada chega
Seção intitulada “Nada chega”- Destino pausado, por você ou pela pausa automática (
auto_paused). Cada evento novo vira uma entregafailedcomdestination_paused. Retome o destino e reenvie as falhas (abaixo). - Filtro não casa. Confira
event_types(*,message.*ou o tipo exato) e se o destino é de uma conexão ou global (connection_id: null). Um destino de conexão só recebe os eventos dela; eventos de organização, comoorg.standing_changed, só chegam a destinos globais. Veja Filtros. - Conexão que não está Ativa. Confira o status dela no painel. Se estiver Restrita, Desativada ou Desconectada, veja Número restrito ou banido.
- URL recusada na criação:
400destination_url_not_allowed. Rede privada,httpe host inválido não são aceitos. Use uma URLhttpspública;details[].messagediz o motivo.
Chega, mas aparece como falha
Seção intitulada “Chega, mas aparece como falha”Sucesso é uma resposta 2xx em até 10 segundos, no total. Qualquer outra coisa conta como falha: outro status, tempo esgotado, erro de rede ou endereço bloqueado. Redirecionamento (3xx) não é seguido e conta como falha.
Responda 2xx rápido e processe depois, numa fila sua. Trabalho pesado dentro da requisição estoura o tempo.
A assinatura não confere
Seção intitulada “A assinatura não confere”As cinco causas de Erros comuns:
- JSON re-serializado: assine o corpo cru, nunca
JSON.stringify(req.body). - Relógio fora da tolerância de 5 minutos: sincronize o servidor (NTP).
- Espaço ou quebra de linha no fim do segredo (comum em
.env). - Segredo sem o prefixo: a chave é o segredo inteiro, com
whsec_. - Corpo lido com outro charset: leia os bytes como UTF-8.
Durante a rotação do segredo vão dois valores v1 no cabeçalho, um por segredo ativo. Basta um conferir.
Evento repetido ou fora de ordem
Seção intitulada “Evento repetido ou fora de ordem”A entrega é pelo menos uma vez. Desduplique por Messajo-Event-Id (o mesmo id do envelope) e, dentro de uma conversa, ordene por sequence. Veja Ordem e duplicatas.
Quantas vezes ele tenta
Seção intitulada “Quantas vezes ele tenta”1 tentativa imediata e mais 14, ao longo de pouco mais de 23 horas: esperas de 10 s, 30 s, 1 min, 2 min, 5 min, 10 min, 20 min, 40 min, 1 h, 2 h, 3 h, 4 h, 6 h e 6 h. Cada espera varia ±10 % e nenhuma tentativa sai depois de 24 horas da criação da entrega. A tabela completa está em Tentativas e falhas.
O destino foi pausado sozinho
Seção intitulada “O destino foi pausado sozinho”O destino é pausado quando junta 10 falhas seguidas e está falhando há pelo menos 24 horas. Qualquer 2xx zera a contagem. Ao pausar, donos e admins recebem um e-mail. Detalhes em Pausa automática.
Recuperar o que ficou para trás
Seção intitulada “Recuperar o que ficou para trás”Corrija o endpoint, retome o destino e reenvie as falhas: Reenviar falhas no painel, ou a API com since (até 1000 por chamada; com has_more: true, chame de novo).
curl -X POST https://api.messajo.com/v1/destinations/$DESTINATION_ID/redeliver-failed \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "since": "2026-11-17T00:00:00Z" }'const { queued, has_more } = await messajo.destinations.redeliverFailed( destinationId, { since: "2026-11-17T00:00:00Z" });A resposta é { queued, has_more }. Entregas e eventos ficam guardados por 30 dias. Veja Lista de falhas e reenvio.
Desenvolvendo sem URL pública
Seção intitulada “Desenvolvendo sem URL pública”Se o seu processo não tem URL pública (script, desktop, ambiente local), veja o destino WebSocket.