Fila pausada

Quando um Webhook apresenta falhas consecutivas de entrega, o Asaas realiza novas tentativas com intervalos progressivos. Após 15 falhas consecutivas, a fila daquela configuração é interrompida.

A interrupção ocorre por configuração de Webhook. Outros Webhooks da mesma conta continuam funcionando normalmente.

Quando uma entrega é considerada bem-sucedida

Para confirmar o recebimento do evento, o endpoint deve retornar:

HTTP 200 OK

Qualquer outro código HTTP, incluindo 201, 204, 3xx, 4xx e 5xx, é tratado como falha de entrega.

Falhas de conexão e timeouts também entram no ciclo de retentativas.

Entenda os intervalos e tentativas em Penalização de filas.

O que acontece quando a fila é interrompida

Após 15 falhas consecutivas:

• nenhum novo evento daquela configuração é enviado;
• novos eventos continuam sendo gerados;
• os eventos pendentes ficam armazenados;
• a configuração permanece interrompida até ser reativada;
• eventos armazenados por mais de 14 dias são excluídos permanentemente.

Você também receberá notificações por e-mail durante o processo de falha e interrupção.

Exemplo de funcionamento

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Enviar<br/>PAYMENT_CREATED"] --> B["Endpoint retorna<br/>HTTP 500"]
    B --> C["Realizar novas tentativas"]
    C --> D["Atingir 15 falhas consecutivas"]
    D --> E["Interromper a fila"]
    E --> F["Continuar armazenando<br/>novos eventos"]
    F --> G["Corrigir o endpoint"]
    G --> H["Reativar a fila"]
    H --> I["Retomar os envios"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    class A inicio
    class B,C,D,E,F,G,H validacao
    class I sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

Após a reativação, os eventos pendentes voltam a ser processados.

Em Webhooks com envio Sequencial, a ordem dos eventos é preservada. No envio Não Sequencial, as notificações podem ser processadas em paralelo e não há garantia de ordem.

Consulte os Tipos de envio.

Identifique a causa da interrupção

Você receberá e-mails automáticos sobre as falhas. Também é possível verificar a situação da configuração em:

Integrações → Webhooks

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

Para descobrir a causa, consulte os Logs de Webhooks.

Os logs permitem verificar:

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

Comportamento por tipo de resposta

Se o log indicar um erro específico, consulte:

• 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

O que fazer com uma fila interrompida

Antes de reativar a configuração:

1. consulte os Logs de Webhooks;
2. identifique a causa das falhas;
3. corrija o endpoint;
4. valide que ele consegue receber e persistir o evento;
5. reative a fila.

A aplicação deve persistir o evento e responder HTTP 200 sem depender da conclusão de processamentos demorados. Execute regras adicionais de forma assíncrona.

Como os Webhooks seguem o modelo at least once, implemente idempotência para tratar possíveis reenvios.

Consulte como implementar idempotência em Webhooks.

Para reativar pelo painel ou pela API, siga o guia Como reativar fila interrompida.

• persistir o evento antes de responder HTTP 200;
• processar regras de negócio de forma assíncrona;
• monitorar os Logs de Webhooks;
• implementar idempotência para suportar reenvios;
• corrigir a causa da falha antes de reativar a fila;
• não manter a fila interrompida por mais de 14 dias.

Próximos passos

• Consulte os Logs de Webhooks
• Entenda a Penalização de filas
• Reative uma fila interrompida
• Implemente idempotência em Webhooks
• Entenda os Tipos de envio