# 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

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**

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

**TypeScript**

```ts
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

- **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](#recuperar-o-que-ficou-para-trás)).
- **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](/webhooks/events/#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](/troubleshooting/number-restricted/).
- **URL recusada na criação:** `400` [`destination_url_not_allowed`](/errors#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.

## 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

As cinco causas de [Erros comuns](/webhooks/verify-signature/#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](/webhooks/verify-signature/#girar-o-segredo-sem-parar) vão dois valores `v1` no cabeçalho, um por segredo ativo. Basta um conferir.

## 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](/webhooks/events/#ordem-e-duplicatas).

## 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](/webhooks/events/#tentativas-e-falhas).

## 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](/webhooks/events/#pausa-automática).

## 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**

```bash
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" }'
```

**TypeScript**

```ts
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](/webhooks/events/#lista-de-falhas-e-reenvio).

## Desenvolvendo sem URL pública

Se o seu processo não tem URL pública (script, desktop, ambiente local), veja o destino [WebSocket](/webhooks/destinations/#websocket).
