Pular para o conteúdo

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.

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.

Janela do terminal
curl -X POST https://api.messajo.com/v1/destinations/$DESTINATION_ID/test \
-H "Authorization: Bearer $MESSAJO_API_KEY"

O teste vai só para esse destino, numa tentativa única, mesmo com ele pausado.

  • Destino pausado, por você ou pela pausa automática (auto_paused). Cada evento novo vira uma entrega failed com destination_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, como org.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: 400 destination_url_not_allowed. Rede privada, http e host inválido não são aceitos. Use uma URL https pública; details[].message diz o motivo.

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.

As cinco causas de Erros comuns:

  1. JSON re-serializado: assine o corpo cru, nunca JSON.stringify(req.body).
  2. Relógio fora da tolerância de 5 minutos: sincronize o servidor (NTP).
  3. Espaço ou quebra de linha no fim do segredo (comum em .env).
  4. Segredo sem o prefixo: a chave é o segredo inteiro, com whsec_.
  5. 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.

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.

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 é 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.

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).

Janela do terminal
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" }'

A resposta é { queued, has_more }. Entregas e eventos ficam guardados por 30 dias. Veja Lista de falhas e reenvio.

Se o seu processo não tem URL pública (script, desktop, ambiente local), veja o destino WebSocket.