Bom saber - Limitações de webhooks e comportamento do sistema

Entender como o finlight trata erros, reenvios e limitações de webhooks ajuda você a criar integrações mais confiáveis e a gerenciar sua cota de forma eficaz.

Tratamento de erros e reenvios

Lógica de reenvio

Quando uma entrega de webhook falha, o finlight reenvia a requisição automaticamente:

Cronograma de reenvio:

• 1º reenvio: Imediatamente após a falha inicial
• 2º reenvio
• 3º reenvio

Máximo de tentativas:

• Um total de 3 tentativas de entrega por evento de webhook
• Cada reenvio usa a mesma carga e os mesmos cabeçalhos
• Todas as tentativas de reenvio são registradas no seu histórico de chamadas

O que aciona os reenvios

Os reenvios ocorrem para:

• Códigos de erro HTTP respostas 4xx e 5xx
• Tempos limite de rede (limite de 5 segundos)
• Falhas de conexão (erros de DNS, conexões recusadas)
• Erros SSL/TLS (problemas de certificado)

O que não aciona reenvios

Não há reenvios para:

• Respostas HTTP 2xx (consideradas bem-sucedidas)
• Configuração de webhook inválida (URLs malformadas)
• Webhooks desativados

Proteção de desativação automática

Rastreamento de falhas consecutivas

O finlight rastreia falhas consecutivas de webhook para proteger sua cota e evitar tentativas fracassadas intermináveis.

Como funciona:

1. O sucesso reinicia o contador - Qualquer entrega bem-sucedida (HTTP 2xx) reinicia o contador de falhas para 0
2. As falhas incrementam o contador - Cada entrega com falha aumenta a contagem de falhas consecutivas
3. Desativação automática em 10 - Após 10 falhas consecutivas, o webhook é desativado automaticamente

Comportamento da desativação automática

Quando a desativação automática é acionada:

• 10 entregas com falha consecutivas em todas as tentativas de reenvio
• O status do webhook muda de "habilitado" para "desabilitado"
• Aparece uma notificação no painel indicando a desativação automática
• Nenhuma outra tentativa de webhook até a reativação manual

Observações importantes:

• Apenas falhas consecutivas contam para a desativação automática
• Qualquer entrega bem-sucedida reinicia o contador para 0
• É necessária reativação manual - os webhooks não se reativam sozinhos
• Todos os tipos de falha contam (tempos limite, respostas 4xx, 5xx)

Cenários de exemplo

Cenário 1: Reinício do contador

Attempt 1: Failed (counter = 1)
Attempt 2: Failed (counter = 2)
Attempt 3: Success (counter = 0) ← Reset!
Attempt 4: Failed (counter = 1)

Cenário 2: Desativação automática

Attempts 1-10: All failed (counter = 10)
→ Webhook automatically disabled

Recuperação e reativação

Processo de reativação manual

Passos para reativar:

1. Identifique a causa raiz usando o histórico de chamadas
2. Corrija os problemas do endpoint (autenticação, URL, erros do servidor)
3. Reative o webhook no detalhe do webhook editando a configuração de status
4. Teste o webhook manualmente com o botão de teste do painel
5. Monitore as entregas iniciais para confirmar a resolução

Estratégias de prevenção

Evitar a desativação automática:

• Implemente um tratamento de erros adequado no seu endpoint
• Retorne códigos de status HTTP apropriados
• Monitore a saúde do webhook de forma proativa
• Configure alertas para as falhas de webhook
• Teste as alterações em desenvolvimento antes da produção

Gestão de cota

Você pode ver seu uso no gráfico do painel. Lembre-se de que o uso é registrado com atraso.

As requisições com falha contam para a cota

Importante: Todas as tentativas de entrega de webhook contam para a cota da sua assinatura, incluindo as entregas com falha.

O que conta:

• Tentativas de entrega iniciais - contam para a cota
• Todas as tentativas de reenvio - cada reenvio conta separadamente
• Entregas com falha - ainda consomem cota
• Requisições de teste de webhook - também contam para a cota

Exemplo de impacto na cota:

1 webhook event with 5 failed retry attempts = 5 quota usage
1 webhook event with 1 successful delivery = 1 quota usage

Gerenciar a cota de forma eficiente

Melhores práticas:

• Corrija rapidamente os problemas do endpoint para minimizar os reenvios com falha
• Monitore o histórico de chamadas em busca de padrões de falha
• Teste minuciosamente antes de habilitar webhooks em produção
• Use um tratamento de erros adequado para retornar os códigos de status corretos

Proteção de cota: O recurso de desativação automática ajuda a evitar o desperdício de cota ao interromper as entregas para endpoints que falham de forma constante.

Para orientação sobre a configuração de webhooks, consulte a documentação principal de webhooks. Para testes e depuração, consulte o guia de testes.