Penalização de filas

Para garantir a estabilidade do sistema de Webhooks e fornecer previsibilidade sobre as tentativas de entrega, o Asaas utiliza um mecanismo de penalização progressiva. Sempre que o endpoint configurado começar a retornar falhas, os novos envios passam a respeitar intervalos crescentes entre as tentativas.

Esse comportamento evita sobrecarga tanto no sistema do Asaas quanto na aplicação que está apresentando problemas, permitindo que o integrador tenha tempo para identificar e corrigir a causa das falhas.

Este mecanismo se aplica tanto aos Webhooks configurados no modo Sequencial quanto no modo Não Sequencial.

Quando ocorre a penalização?

A penalização acontece quando o endpoint do webhook retorna qualquer resposta diferente da família HTTP 2xx, por exemplo:

• 400 Bad Request
• 403 Forbidden
• 404 Not Found
• 408 Read Timed Out
• 500 Internal Server Error
• Falhas de conexão
• Timeouts

Cada tentativa malsucedida aumenta o intervalo até a próxima tentativa.

Como funciona a penalização?

Após a primeira falha, o Asaas inicia automaticamente um ciclo progressivo de retentativas:

Após 15 falhas consecutivas, a fila do webhook será interrompida.

O que acontece quando a fila é pausada?

Quando a fila é pausada:

• Novos eventos continuam sendo gerados normalmente.
• Os eventos permanecem armazenados em fila.
• Nenhum novo envio será realizado até que a fila seja reativada.
• Os eventos permanecem disponíveis por até 14 dias.
• Eventos com mais de 14 dias serão excluídos permanentemente.

📘

Importante

A interrupção ocorre por configuração de webhook. Caso existam outros webhooks cadastrados, eles continuarão funcionando normalmente.

Impacto do modo Sequencial

No modo Sequencial, a ordem de entrega é garantida.

Isso significa que, se um evento estiver penalizado, todos os eventos seguintes daquela fila permanecerão aguardando até que o evento atual seja entregue com sucesso.

Exemplo:

PAYMENT_CREATED
↓
PAYMENT_CONFIRMED
↓
PAYMENT_RECEIVED
↓
PAYMENT_REFUNDED

Se o envio do PAYMENT_CONFIRMED estiver penalizado, os eventos PAYMENT_RECEIVED e PAYMENT_REFUNDED não serão enviados até que o evento pendente seja processado.

📘

Importante

Caso a aplicação dependa da ordem cronológica dos eventos, recomenda-se utilizar o envio Sequencial.

Fluxo de penalização

Evento enviado
↓
Erro no endpoint
↓
Nova tentativa automática
↓
Intervalos progressivos
↓
15 falhas consecutivas
↓
Fila pausada
↓
Correção do problema
↓
Remoção da penalização
↓
Retomada dos envios

Removendo a penalização

Após identificar e corrigir o problema na aplicação, não é necessário aguardar o fim do ciclo de retentativas.

É possível solicitar que o Asaas remova a penalização e tente reenviar imediatamente o primeiro evento da fila.

Via interface web

Acesse:

Integrações → Webhooks

Existe uma coluna ao lado da situação da configuração exibindo a quantidade de eventos penalizados.

1. Acesse o webhook que apresenta eventos penalizados.
2. Clique em Remover penalização.
3. Confirme a ação.

Via API

Também é possível remover a penalização programaticamente utilizando o endpoint específico.

Confira a referência completa deste endpoint

🚧

Atenção

Este endpoint possui um rate limit mais restrito para desencorajar automações que removam a penalização repetidamente.

A funcionalidade foi projetada para ser utilizada somente após a correção do problema que causou as falhas.

Boas práticas

📘

Recomendamos

• Monitorar os Logs de Webhooks regularmente.
• Processar os eventos de forma assíncrona.
• Garantir que o endpoint responda rapidamente.
• Implementar idempotência para suportar reenvios.
• Investigar erros antes de remover a penalização.
• Não automatizar a remoção contínua da penalização.
• Configurar alertas para monitorar indisponibilidades.

Próximos passos

Após entender como funciona a penalização, recomendamos a leitura dos seguintes conteúdos:

• Receba eventos do Asaas no seu endpoint de Webhook;

• Como implementar idempotência em Webhooks;

• Eventos de Webhooks;

• Tipos de envio;

• Logs de Webhooks;

• Penalização de filas;

• Fila pausada;

• Erro 400 (Bad Request);

• Erro 403 (Forbidden);

• Erro 404 (Not Found);

• Erro 408 (Read Timed Out);

• Erro 500 (Internal Server Error);

• Erro Connect Timed Out;

• IPs oficiais do Asaas;
• Bloqueio do Firewall na CloudFlare.