---
updatedAt: 2026-09-01T13:50:42.000Z
agentTools:
  projectIndex: https://docs.asaas.com/llms.txt
---

# 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

1. Confirme se a URL do webhook está acessível.
2. Verifique o código e o tempo de resposta do endpoint.
3. Analise os logs das tentativas com falha.
4. Identifique operações executadas antes da resposta.
5. Remova consultas e regras de negócio do fluxo síncrono.
6. Retorne sucesso após validar o recebimento da requisição.
7. Execute os processamentos mais pesados em segundo plano.
8. Teste novamente, inclusive em períodos de maior volume.

### Fluxo de diagnóstico

#### 1. Entrega e resposta do endpoint

```mermaid
%%{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
```

<br />

#### 2. Análise do tempo de resposta

```mermaid
%%{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
```

<br />

> O primeiro fluxo responde **“o webhook chegou e recebeu sucesso?”**, enquanto o segundo responde **“por que a resposta está lenta?”**.&#x20;

<br />

#### 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.**

<br />

# Sibling pages

* [Webhook recebido, mas não persistido](https://docs.asaas.com/docs/webhook-recebido-mas-não-persistido.md)
* [API Key usada no ambiente errado](https://docs.asaas.com/docs/api-key-de-sandbox-usada-em-produção.md)
* [Sistema dependente apenas da resposta síncrona](https://docs.asaas.com/docs/sistema-dependente-apenas-da-resposta-síncrona.md)
* [Cobrança duplicada após retry sem idempotência](https://docs.asaas.com/docs/cobrança-duplicada-após-retry-sem-idempotência.md)
* [Entidade criada sem vínculo com o registro interno](https://docs.asaas.com/docs/entidade-criada-sem-vínculo-com-o-registro-interno.md)
* [Status local divergente do Asaas](https://docs.asaas.com/docs/status-local-divergente-do-asaas.md)
* [Requisições bloqueadas por ausência de controle de limites](https://docs.asaas.com/docs/requisições-bloqueadas-por-ausência-de-controle-de-limites.md)
* [Listagem incompleta por ausência de paginação](https://docs.asaas.com/docs/listagem-incompleta-por-ausência-de-paginação.md)
* [Webhook duplicado processado sem idempotência](https://docs.asaas.com/docs/webhook-duplicado-processado-sem-idempotência.md)