Entregas e novas tentativas

Quando uma entrega é bem-sucedida

A entrega conta como bem-sucedida quando o seu endpoint responde qualquer status 2xx em até 10 segundos. O corpo da resposta é ignorado.

Conta como falha: status fora de 2xx, demora maior que 10 segundos ou erro de conexão (DNS, certificado, servidor fora do ar).

Novas tentativas

Se a entrega falhar, a TopTalking tenta de novo. São até 6 tentativas no total:

Tentativa	Quando
1ª	Imediatamente
2ª	1 minuto depois
3ª	5 minutos depois
4ª	30 minutos depois
5ª	2 horas depois
6ª	6 horas depois

Depois da última falha, a entrega fica com status failed. Você pode reenviá-la pelo painel (veja abaixo).

Deduplicação

O id do evento é o mesmo em todas as tentativas (também no cabeçalho X-TopTalking-Event-Id). Como uma entrega pode chegar mais de uma vez — por exemplo, se o seu servidor processou mas demorou a responder —, guarde os IDs já processados e ignore repetições:

Tabela simples de controle (PostgreSQL)

create table eventos_toptalking (
  id uuid primary key,          -- evento.id
  tipo text not null,
  recebido_em timestamptz not null default now()
);

-- No receptor: só processe se o insert funcionar.
insert into eventos_toptalking (id, tipo) values ($1, $2)
on conflict (id) do nothing
returning id;

Ordem não garantida

Eventos podem chegar fora de ordem (retentativas, paralelismo). Exemplos:

• um message.status_updated com read pode chegar antes do de delivered;
• dois contact.updated seguidos podem chegar invertidos.

Para não voltar um estado no tempo, compare created_at do evento (ou updated_at do contato) com o que você já tem salvo antes de sobrescrever. Se precisar do estado mais atual com certeza, busque o recurso na API (ex.: GET /contacts/{contact_id}).

Desativação automática

Se um endpoint só falhar por 3 dias seguidos, a TopTalking o desativa automaticamente: enabled vira false e disabled_reason explica o motivo. Enquanto estiver desativado, ele não recebe novos eventos.

Para reativar, corrija o problema e:

• no painel, reative o webhook em Configurações → Desenvolvedor → Webhooks; ou
• pela API: PATCH /webhooks/{webhook_id} com { "enabled": true }.

Antes de reativar, use Enviar teste para confirmar que o endpoint voltou a responder 2xx.

Histórico e reenvio

• No painel: menu do webhook → Ver entregas. Mostra cada tentativa com o status HTTP, o tempo de resposta e o erro. Entregas com falha têm o botão Reenviar.
• Pela API: GET /webhooks/{webhook_id}/deliveries.
• Os eventos ficam guardados por 30 dias.

Boas práticas

• Responda primeiro, processe depois. Valide a assinatura, coloque o evento numa fila ou tabela e responda 200. Processamentos longos (chamar outra API, gerar PDF, rodar IA) devem rodar em segundo plano.
• Seja idempotente com o id do evento.
• Não confie na ordem; use created_at.
• Monitore last_delivery_status e disabled_reason em GET /webhooks.
• Ignore tipos desconhecidos com 2xx: novos eventos podem ser adicionados no futuro.