Fila pausada

Quando ocorre uma falha na comunicação entre o Asaas e o endpoint configurado, o evento não é descartado imediatamente.

O Asaas realiza novas tentativas de entrega utilizando um mecanismo de penalização progressiva. Caso ocorram 15 falhas consecutivas, a fila daquele webhook é interrompida automaticamente para evitar o envio contínuo para um endpoint indisponível.

A interrupção acontece por configuração de webhook. Outros webhooks configurados na conta continuam funcionando normalmente.

Como funciona o envio dos eventos

Sempre que ocorrer uma alteração em algum recurso integrado, o Asaas enviará uma requisição POST para a URL configurada.

Para que a entrega seja considerada bem-sucedida, o endpoint deve retornar:

HTTP 200 OK

📘
Importante
Embora os códigos da família 2xx representem sucesso no protocolo HTTP, o Asaas considera como entrega bem-sucedida apenas respostas HTTP 200.

Qualquer outro retorno (201, 204, 308, 400, 403, 404, 500, etc.) será interpretado como falha na comunicação.

O que acontece quando ocorrem falhas?

Após uma falha, o Asaas continua tentando enviar o mesmo evento.

Caso ocorram 15 tentativas consecutivas sem sucesso:

a fila daquele webhook é interrompida;
novos eventos continuam sendo gerados normalmente;
os eventos permanecem armazenados;
nenhum novo evento será enviado até que a fila seja reativada.

Você receberá notificações por e-mail durante esse processo.

O que acontece com os eventos durante a interrupção?

Mesmo com a fila pausada:

os eventos continuam sendo gerados;
os eventos ficam armazenados temporariamente;
ao reativar a fila, os eventos acumulados serão reenviados na ordem em que estavam armazenados;
eventos com mais de 14 dias serão excluídos permanentemente.

🚧
Atenção
Caso a fila permaneça interrompida por mais de 14 dias, os eventos mais antigos serão removidos e não poderão ser recuperados.

Exemplo de funcionamento

PAYMENT_CREATED
↓
Endpoint retorna HTTP 500
↓
Asaas tenta novamente
↓
15 falhas consecutivas
↓
Fila interrompida
↓
Novos eventos continuam sendo gerados
↓
Problema é corrigido
↓
Fila é reativada
↓
Eventos acumulados são reenviados

Como identificar que a fila foi interrompida?

Você receberá e-mails automáticos informando as falhas.

Além disso, é possível verificar a situação da fila em:

Integrações → Webhooks

Na configuração afetada será exibido o status de fila interrompida.

Como descobrir a causa do problema?

A melhor forma é consultar os logs do webhook.

Veja mais em:

Como visualizar logs de Webhooks

Os logs permitem identificar:

código HTTP retornado;
mensagem de erro;
horário das tentativas;
payload enviado;
quantidade de reenvios.

Códigos HTTP e comportamento do Webhook

HTTP 200 - Sucesso

Indica que o evento foi processado corretamente.

Resultado: o evento é considerado entregue e removido da fila.

HTTP 3xx - Redirecionamento

O endpoint tentou redirecionar a requisição para outra URL.

O Asaas não segue redirecionamentos automaticamente.

Resultado: a entrega falha e o evento entra no ciclo de retentativas.

HTTP 4xx - Erro do cliente

Normalmente indica:

URL incorreta;
autenticação inválida;
validação do payload;
bloqueio da requisição.

Resultado: o evento continuará sendo reenviado até atingir o limite de tentativas.

HTTP 5xx - Erro interno do servidor

Indica que o endpoint recebeu a requisição, mas não conseguiu processá-la.

As causas mais comuns são:

indisponibilidade do servidor;
timeout;
exceções da aplicação;
indisponibilidade do banco de dados.

Resultado: o evento continuará sendo reenviado automaticamente.

Boas práticas

📘
Recomendamos

sempre retornar HTTP 200 após processar o evento;
processar o webhook de forma assíncrona;
implementar idempotência para suportar reenvios;
monitorar os Logs de Webhooks;
corrigir a causa da falha antes de reativar a fila;
não deixar a fila interrompida por mais de 14 dias.

Guias para erros específicos

Caso você encontre algum erro nos logs, consulte:

Próximos passos

Após entender o funcionamento da fila interrompida, recomendamos a leitura dos seguintes conteúdos: