Como reativar fila interrompida

O Asaas interrompe automaticamente a fila de Webhooks após 15 falhas consecutivas no envio das notificações.

Quando isso acontece, os novos eventos continuam sendo gerados, porém deixam de ser enviados até que a fila seja reativada.

Por isso, antes de reativar a sincronização, é fundamental identificar e corrigir a causa do problema.

Impactos da fila interrompida

Com a fila interrompida:

• novos eventos continuam sendo criados normalmente;
• os eventos deixam de ser enviados para a aplicação;
• a sincronização entre os sistemas fica interrompida;
• cobranças, pagamentos, assinaturas e demais recursos podem deixar de ser atualizados no sistema integrado;
• eventos armazenados por mais de 14 dias serão excluídos permanentemente.

🚧

Atenção

Reativar a fila sem corrigir a causa do problema fará com que ela seja interrompida novamente após novas falhas consecutivas.

Passo 1: Verifique os logs do webhook

Antes de reativar a fila, consulte os logs para identificar o erro que está ocorrendo.

Veja mais em:

Como visualizar os logs de Webhook

Os logs permitem verificar:

• código HTTP retornado;
• payload enviado;
• horário da tentativa;
• quantidade de reenvios;
• mensagem de erro recebida pelo Asaas.

Passo 2: Corrija o problema na aplicação

Após identificar a causa da falha, corrija o comportamento do endpoint.

As causas mais comuns são:

• URL incorreta;
• timeout no processamento;
• erro interno da aplicação;
• firewall bloqueando os IPs do Asaas;
• retorno HTTP diferente de 200;
• indisponibilidade do servidor;
• validações que rejeitam o payload recebido.

Caso necessário, consulte:

• 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
• Outros erros

🚧

Importante

A fila deve ser reativada somente após a correção da falha, garantindo que a aplicação esteja pronta para receber novos eventos.

Passo 3: Reativando via painel

Após corrigir o problema, acesse:

Menu do usuário → Integrações → Webhooks

Localize a configuração interrompida e reative a fila.

Reativando via API

Também é possível reativar programaticamente utilizando a atualização da configuração do webhook.

Basta enviar o atributo:

{
  "interrupted": false
}

Utilize o endpoint de atualização de webhook.

Confira a referência completa deste endpoint

Exemplo de fluxo de recuperação

Falhas consecutivas
↓
Fila interrompida
↓
Consulta aos logs
↓
Identificação do problema
↓
Correção da aplicação
↓
Reativação da fila
↓
Eventos acumulados são reenviados
↓
Sincronização normalizada

Boas práticas

📘

Recomendamos

• Monitorar os logs periodicamente.
• Implementar idempotência para suportar reenvios.
• Processar os eventos de forma assíncrona.
• Garantir que o endpoint responda rapidamente.
• Sempre retornar HTTP 200 após processar o evento.
• Verificar se o firewall não está bloqueando os IPs do Asaas.
• Não reativar a fila sem corrigir a causa da falha.

📌

Importante

Se você acabou de criar um novo webhook e ele já aparece como interrompido, verifique se a fila de sincronização da configuração está ativa.

Próximos passos

Após reativar a fila, recomendamos a leitura dos seguintes conteúdos:

• Logs de Webhooks;
• Penalização de filas;
• Fila pausada;
• Como implementar idempotência em Webhooks;
• IPs oficiais do Asaas;
• Bloqueio do Firewall na Cloudflare.