Webhook com timeout ou resposta demorada
Esse erro ocorre quando o Asaas envia o webhook, mas o endpoint não retorna uma resposta de sucesso dentro do tempo esperado.
Normalmente, isso acontece porque o endpoint está indisponível, apresenta instabilidade ou executa regras de negócio e consultas externas antes de responder.
Como identificar
- o webhook apresenta falha, timeout ou reenvio;
- o endpoint retorna erro ou demora para responder;
- a falha ocorre principalmente em períodos de maior volume;
- o endpoint consulta banco de dados, ERP ou serviços externos antes da resposta;
- o problema ocorre de forma intermitente;
- os logs mostram processamento iniciado antes do retorno ao Asaas.
Como corrigir
- Confirme se a URL do webhook está acessível.
- Verifique o código e o tempo de resposta do endpoint.
- Analise os logs das tentativas com falha.
- Identifique operações executadas antes da resposta.
- Remova consultas e regras de negócio do fluxo síncrono.
- Retorne sucesso após validar o recebimento da requisição.
- Execute os processamentos mais pesados em segundo plano.
- Teste novamente, inclusive em períodos de maior volume.
Fluxo de diagnóstico
1. Entrega e resposta do endpoint
%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7
}}}%%
flowchart TD
A["O webhook apresentou falha ou timeout"] --> B{"Existe tentativa de envio registrada?"}
B --> BSim(("Sim"))
B --> BNao(("Não"))
BNao --> C["Verificar URL, eventos configurados e fila"]
C --> D["Corrigir a configuração e testar novamente"]
BSim --> E{"O endpoint está acessível?"}
E --> ESim(("Sim"))
E --> ENao(("Não"))
E --> EDuvida(("Não sabe"))
ENao --> F["Restabelecer a disponibilidade do endpoint"]
F --> G["Testar novamente"]
EDuvida --> H["Testar a URL e consultar os logs"]
H --> E
ESim --> I{"O endpoint retornou sucesso?"}
I --> ISim(("Sim"))
I --> INao(("Não"))
INao --> J["Verificar o código de resposta e o erro interno"]
J --> K["Corrigir a falha"]
ISim --> L["Seguir para a análise do tempo de resposta"]
K --> L
classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
classDef correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px
classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
classDef respostaDuvida fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px
class A inicio
class B,E,I decisao
class F,K correcao
class D,G,H,L validacao
class C,J analise
class BSim,ESim,ISim respostaSim
class BNao,ENao,INao respostaNao
class EDuvida respostaDuvida
linkStyle default stroke:#94A3B8,stroke-width:2px
linkStyle 1,6,14 stroke:#22C55E,stroke-width:4px
linkStyle 2,7,15 stroke:#EF4444,stroke-width:4px
linkStyle 8 stroke:#8B5CF6,stroke-width:4px
2. Análise do tempo de resposta
%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7
}}}%%
flowchart TD
A["O endpoint está acessível e retorna uma resposta"] --> B{"A resposta ocorreu no tempo esperado?"}
B --> BSim(("Sim"))
B --> BNao(("Não"))
BSim --> C["Manter métricas e monitoramento"]
BNao --> D{"Há processamento antes da resposta?"}
D --> DSim(("Sim"))
D --> DNao(("Não"))
D --> DDuvida(("Não sabe"))
DDuvida --> E["Mapear as operações executadas pelo endpoint"]
E --> F{"Existem consultas a sistemas externos?"}
DSim --> F
DNao --> G["Verificar infraestrutura, rede e capacidade"]
G --> H["Ajustar a causa da lentidão"]
F --> FSim(("Sim"))
F --> FNao(("Não"))
F --> FDuvida(("Não sabe"))
FSim --> I["Remover consultas externas do fluxo síncrono"]
FNao --> J["Remover regras de negócio do fluxo síncrono"]
FDuvida --> E
I --> K["Mover o processamento para segundo plano"]
J --> K
K --> L["Retornar sucesso após validar o recebimento"]
H --> M["Testar novamente"]
L --> M
M --> N{"A resposta ocorreu no tempo esperado?"}
N --> NSim(("Sim"))
N --> NNao(("Não"))
NSim --> C
NNao --> O["Coletar evidências para análise técnica"]
classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
classDef correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px
classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
classDef respostaDuvida fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px
class A inicio
class B,D,F,N decisao
class H,I,J,K,L correcao
class M validacao
class C sucesso
class E,G,O analise
class BSim,DSim,FSim,NSim respostaSim
class BNao,DNao,FNao,NNao respostaNao
class DDuvida,FDuvida respostaDuvida
linkStyle default stroke:#94A3B8,stroke-width:2px
linkStyle 1,5,13,25 stroke:#22C55E,stroke-width:4px
linkStyle 2,6,14,26 stroke:#EF4444,stroke-width:4px
linkStyle 7,15 stroke:#8B5CF6,stroke-width:4px
O primeiro fluxo responde “o webhook chegou e recebeu sucesso?”, enquanto o segundo responde “por que a resposta está lenta?”.
Como prevenir
Mantenha o endpoint disponível e com o mínimo de processamento antes da resposta. Consultas externas e regras de negócio devem ocorrer em segundo plano. Monitore tempo de resposta, erros e variações de volume.
O endpoint deve responder rapidamente. O processamento acontece depois.
Updated about 12 hours ago
Did this page help you?