Webhook Logs

Use the Webhook Logs to check the delivery attempts made by Asaas, identify endpoint failures and track situations that may lead to queue penalties or interruption.

❗️
Important
Asaas keeps Webhook logs and events for up to 14 days.
If communication failures occur, an email will be sent to the address configured in the webhook notifications.
If the queue remains interrupted for more than 14 days, pending events will be permanently removed and cannot be recovered.

Access the Webhook Logs

Go to Webhook Logs in the Integrations area of your account.

Delivery logs are available only through the web interface. Webhook configuration can also be managed through the API.

Webhook Logs for you to check communication errors that occurred.

What to check in the logs

For each delivery attempt, use the logs to analyze:

Information	How to use it
Event sent	Identify which notification had a problem.
Date and time	Correlate the attempt with your application's logs.
Endpoint	Confirm which URL received the request.
HTTP code	Identify how your application responded to Asaas.
Communication error	Check for failures that occurred before or during the connection.
Timeout	Identify delays in the connection or in the endpoint response.
Number of attempts	Track the progression of retries and penalties.

How to investigate a failure

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Notice missing events<br/>or receive an alert"] --> B["Access Webhook Logs"]
    B --> C["Identify the error<br/>or HTTP code"]
    C --> D["Check the cause<br/>in the application"]
    D --> E["Fix the endpoint"]
    E --> F{"Was the queue interrupted?"}

    F --> FSim(("Yes"))
    F --> FNao(("No"))

    FSim --> G["Reactivate the queue"]
    FNao --> H["Validate new events"]
    G --> H

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,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
    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px,font-size:16px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px,font-size:16px

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

    class FSim respostaSim
    class FNao respostaNao

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 5 stroke:#22C55E,stroke-width:4px
    linkStyle 6 stroke:#EF4444,stroke-width:4px

If the queue is interrupted, fix the cause of the failure before reactivating it.

See how to reactivate an interrupted queue.

Main errors found in the logs

Use the recorded code or error to guide the investigation.

Error	What it indicates	How to investigate
`400 Bad Request`	The request reached the endpoint but was rejected by the application.	Error 400 (Bad Request)
`403 Forbidden`	The request reached the server, but a security rule blocked access.	Error 403 (Forbidden)
`404 Not Found`	The configured URL or route was not found.	Error 404 (Not Found)
`408 Read Timed Out`	The connection was established, but the endpoint did not respond within the expected time.	Error 408 - Read Timed Out
`500 Internal Server Error`	The application had an internal failure during processing.	Error 500 (Internal Server Error)
`Connect Timed Out`	Asaas could not establish a connection with the server.	Connect Timed Out error

Consecutive failures enter the queue penalty mechanism. After 15 consecutive failures, the queue for that Webhook may be interrupted.

Understand queue penalties.

Check subaccount logs

The main account can also check the Webhook Logs of its subaccounts.

In Integrações > Logs de Webhooks (Integrations > Webhook Logs):

select the Tipo de Conta (Account Type) filter;
choose Subcontas (Subaccounts);
enter the identifier of the subaccount you want to check.

The query is performed for one subaccount at a time.

📘
We recommend

Regularly monitoring the Webhook logs.

Investigating HTTP codes other than 200.

Quickly fixing failures to avoid queue interruption.

Implementing asynchronous processing to reduce timeouts.

Using idempotence to handle possible redeliveries.

Keeping alerts and monitoring on the endpoint's availability.

Reactivating the queue as soon as the problem is resolved.

Avoiding keeping events pending for long periods.

Next steps

Updated 3 days ago

Did this page help you?