Penalização de filas

Quando o endpoint de um Webhook apresenta falhas consecutivas, o Asaas aumenta progressivamente o intervalo entre as tentativas de entrega.

Esse mecanismo se aplica aos Webhooks com envio Sequencial e Não Sequencial.

Quando a penalização é aplicada

Uma tentativa é considerada falha quando o Asaas não consegue concluir a entrega com HTTP 200.

Isso inclui, por exemplo:

• 201, 204 ou outros códigos diferentes de 200;
• 400 Bad Request;
• 403 Forbidden;
• 404 Not Found;
• 408 Read Timed Out;
• 500 Internal Server Error;
• falhas de conexão;
• timeouts.

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

Intervalos de retentativa

Após 15 falhas consecutivas, a fila do Webhook é interrompida.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Enviar evento"] --> B["Receber falha"]
    B --> C["Aplicar nova tentativa"]
    C --> D["Aumentar intervalo"]
    D --> E["Atingir 15 falhas consecutivas"]
    E --> F["Interromper a fila"]

    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 validacao
    class F sucesso

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

Quando a fila é interrompida

Após a interrupção:

• novos eventos continuam sendo gerados;
• os eventos ficam armazenados na fila;
• nenhum novo envio é realizado até a reativação;
• os eventos permanecem armazenados por até 14 dias;
• eventos com mais de 14 dias são excluídos permanentemente.

Corrija a causa da falha antes de reativar a fila.

Consulte como reativar uma fila interrompida.

Impacto no envio Sequencial

No modo Sequencial, os eventos respeitam a ordem em que ocorreram. Se um evento estiver penalizado, os eventos seguintes daquela fila aguardam sua entrega.

Exemplo:

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["PAYMENT_CREATED"] --> B["PAYMENT_CONFIRMED"]
    B --> C["PAYMENT_RECEIVED"]
    C --> D["PAYMENT_REFUNDED"]

    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 validacao
    class D sucesso

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

Se PAYMENT_CONFIRMED estiver penalizado, PAYMENT_RECEIVED e PAYMENT_REFUNDED permanecerão aguardando.

Para comparar os dois comportamentos, consulte Tipos de envio.

Remova a penalização após corrigir o endpoint

Se a configuração ainda estiver penalizada, mas a causa da falha já tiver sido corrigida, você pode remover o backoff sem aguardar o próximo intervalo automático.

A remoção da penalização não deve ser confundida com a reativação de uma fila já interrompida. Quando a fila atingir 15 falhas e for interrompida, utilize o fluxo de reativação.

Pela aplicação web

Acesse Integrações → Webhooks.

1. localize o Webhook com eventos penalizados;
2. clique em Remover penalização;
3. confirme a ação.

O Asaas poderá tentar novamente o envio sem aguardar o intervalo restante da penalização.

Pela API

Utilize:

POST /v3/webhooks/{id}/removeBackoff

Uma resposta HTTP 204 confirma a remoção da penalização.

Consulte o endpoint Remover penalização de webhook.

Próximos passos

• Consulte os Logs de Webhooks
• Entenda o comportamento da fila pausada
• Reative uma fila interrompida
• Conheça os tipos de envio
• Implemente idempotência em Webhooks