Entrega e falhas

O que acontece entre o evento nascer e o seu servidor confirmar — e o que fazer quando algo dá errado.

Sucesso

Qualquer 2xx confirma o recebimento. Não olhamos o corpo da sua resposta.

Responda assim que receber e processe depois. O timeout é de 10 segundos — passar disso conta como falha e agenda retry, mesmo que você tenha processado tudo corretamente.

Retry

Falha transitória agenda nova tentativa com backoff exponencial:

Tentativa	Espera desde a anterior
1ª repetição	30 segundos
2ª	1 minuto
3ª	2 minutos
4ª	4 minutos
…	dobrando, com teto de 1 hora

São 5 tentativas no total. Esgotadas, a entrega fica como failed e você pode reenviá-la manualmente.

Conta como falha transitória: qualquer resposta não-2xx (exceto 410), timeout, erro de DNS, falha de TLS, conexão recusada.

Retry significa POST repetido

É por isso que a deduplicação pelo id não é opcional. Uma falha de rede depois de você processar, mas antes de nós registrarmos o 200, faz o mesmo evento chegar de novo.

410 Gone: desligar de vez

Responder 410 Gone desativa o endpoint imediatamente, sem retry. Use quando ele acabou mesmo — o serviço foi descontinuado, a rota não existe mais.

Não use 410 para dizer "estou ocupado" ou "em manutenção". Para isso, qualquer outro código de erro serve e o backoff cuida do resto.

Desativação automática

20 falhas consecutivas desativam o endpoint. Um sucesso zera a contagem — o critério é consecutivo, não acumulado, então falhas esparsas ao longo de meses não somam.

O motivo aparece no painel:

Motivo	O que aconteceu
too_many_failures	20 falhas seguidas
endpoint_gone	Você respondeu 410

Desativar não é pausar

Quando um endpoint é desativado, as entregas que já estavam na fila são descartadas na hora — elas não ficam esperando a reativação.

Isso vale também quando você desativa manualmente no painel. Se a intenção é "vou fazer manutenção e volto", saiba que os eventos daquele intervalo não serão entregues sozinhos: o reenvio manual é o caminho de volta.

Reativar pelo painel limpa o motivo e zera a contagem de falhas.

Redirecionamentos não são seguidos

Um 301/302 conta como falha, com o motivo redirect_not_followed. Mudou de endereço? Edite a URL do endpoint.

Isso é uma medida de segurança: validamos a URL que você cadastrou, e seguir um Location permitiria contornar essa validação depois do fato.

Teto por hora

Cada endpoint aceita no máximo 600 entregas por hora (ajustável pelo administrador). O que passa disso vira uma linha com status dropped e o motivo rate_limited.

Descarte é definitivo

Um evento barrado pelo teto não é reprocessado automaticamente numa hora com vaga. Ele aparece no log como dropped, com o payload guardado, e o reenvio manual é a única forma de recuperá-lo.

Se você espera picos (uma campanha grande, uma importação), fale com o administrador da conta para ajustar o teto antes.

O descarte vira linha no log, e não apenas um registro interno, justamente para que "barrado pelo teto" seja distinguível de "nunca aconteceu".

Lendo o log

Em Integrações › Webhooks › Log cada entrega mostra status, código HTTP recebido, número de tentativas e o payload enviado.

Status	Significado
pending	Aguardando a próxima tentativa
processing	Sendo entregue agora
success	Você respondeu 2xx
failed	Esgotou as 5 tentativas
dropped	Descartada pelo teto horário, ou o endpoint foi desativado/removido

O log tem prazo curto de retenção — ele guarda o payload, e payload de resposta contém dados pessoais. Não o use como arquivo permanente: se precisa de histórico, guarde do seu lado.

Reenvio manual

No log, cada entrega tem Reenviar. Isso reabre a mesma entrega — mesmo corpo, mesmo id de evento — com uma tentativa a mais.

É o caminho de recuperação para:

• Entregas failed depois de você consertar o servidor
• Entregas dropped pelo teto horário
• Entregas perdidas enquanto o endpoint estava desativado

Como o id do evento é o mesmo, seu consumidor deduplica normalmente: reenviar algo que já foi processado é seguro.

Diagnóstico

"Não recebo nada"

1. O endpoint está ativo? Confira se não foi desativado automaticamente
2. A URL é https:// e acessível pela internet? localhost e endereços de rede interna são recusados no cadastro
3. Você assinou o tipo certo? Um endpoint que só assina response.created não recebe invite.*
4. Clique em Testar — o ping isola o problema entre configuração e evento

"Recebo, mas o log diz falha"

Provavelmente você está demorando mais de 10s para responder, ou respondendo antes de checar a assinatura e devolvendo 401. Veja o código HTTP registrado no log.

"Recebo o mesmo evento várias vezes"

Esperado — veja deduplicação. Se está acontecendo em todas as entregas, confira se você está mesmo respondendo 2xx dentro do timeout.

"Recebo eventos duplicados com ids diferentes"

Aí não é retry. invite.responded e response.created são eventos distintos do mesmo preenchimento — se você assinou *, vai receber os dois. Filtre por tipo.