Webhook timeout or slow response

This error occurs when Asaas sends the webhook, but the endpoint does not return a success response within the expected time.

This usually happens because the endpoint is unavailable, is unstable, or runs business logic and external queries before responding.

How to identify

• the webhook shows a failure, timeout, or resend;
• the endpoint returns an error or takes too long to respond;
• the failure occurs mainly during higher-volume periods;
• the endpoint queries the database, ERP, or external services before responding;
• the problem occurs intermittently;
• the logs show processing started before the response was returned to Asaas.

How to fix

1. Confirm that the webhook URL is reachable.
2. Check the endpoint's response code and response time.
3. Analyze the logs of the failed attempts.
4. Identify operations executed before the response.
5. Remove queries and business logic from the synchronous flow.
6. Return success after validating receipt of the request.
7. Run heavier processing in the background.
8. Test again, including during higher-volume periods.

Diagnostic flow

1. Delivery and endpoint response

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7
}}}%%
flowchart TD
    A["The webhook failed or timed out"] --> B{"Is there a recorded delivery attempt?"}

    B --> BSim(("Yes"))
    B --> BNao(("No"))

    BNao --> C["Check URL, configured events, and queue"]
    C --> D["Fix the configuration and test again"]

    BSim --> E{"Is the endpoint reachable?"}

    E --> ESim(("Yes"))
    E --> ENao(("No"))
    E --> EDuvida(("Not sure"))

    ENao --> F["Restore endpoint availability"]
    F --> G["Test again"]

    EDuvida --> H["Test the URL and check the logs"]
    H --> E

    ESim --> I{"Did the endpoint return success?"}

    I --> ISim(("Yes"))
    I --> INao(("No"))

    INao --> J["Check the response code and the internal error"]
    J --> K["Fix the failure"]

    ISim --> L["Proceed to the response time analysis"]
    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. Response time analysis

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7
}}}%%
flowchart TD
    A["The endpoint is reachable and returns a response"] --> B{"Did the response arrive within the expected time?"}

    B --> BSim(("Yes"))
    B --> BNao(("No"))

    BSim --> C["Maintain metrics and monitoring"]

    BNao --> D{"Is there processing before the response?"}

    D --> DSim(("Yes"))
    D --> DNao(("No"))
    D --> DDuvida(("Not sure"))

    DDuvida --> E["Map the operations executed by the endpoint"]
    E --> F{"Are there queries to external systems?"}

    DSim --> F

    DNao --> G["Check infrastructure, network, and capacity"]
    G --> H["Address the cause of the slowness"]

    F --> FSim(("Yes"))
    F --> FNao(("No"))
    F --> FDuvida(("Not sure"))

    FSim --> I["Remove external queries from the synchronous flow"]
    FNao --> J["Remove business logic from the synchronous flow"]
    FDuvida --> E

    I --> K["Move processing to the background"]
    J --> K

    K --> L["Return success after validating receipt"]

    H --> M["Test again"]
    L --> M

    M --> N{"Did the response arrive within the expected time?"}

    N --> NSim(("Yes"))
    N --> NNao(("No"))

    NSim --> C
    NNao --> O["Collect evidence for technical analysis"]

    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

The first flow answers “did the webhook arrive and receive success?”, while the second answers “why is the response slow?”.

How to prevent

Keep the endpoint available and with minimal processing before the response. External queries and business logic should happen in the background. Monitor response time, errors, and volume variations.

The endpoint must respond quickly. Processing happens afterwards.