Error 500 (Internal Server Error)

A 500 Internal Server Error in the Webhook Logs indicates that Asaas was able to send the request to the endpoint, but your application had an internal failure during processing.

In this scenario, investigate the application logs, the payload handling, and the dependencies used during the request.

Main causes

The error may occur due to:

• unhandled exceptions;
• database connection failures;
• unavailable external APIs;
• authentication problems with third-party services;
• SQL queries with errors;
• high memory or CPU usage;
• incorrect payload deserialization;
• unavailable dependencies;
• timeouts in internal calls;
• failures in queues or workers.

Failure example

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Asaas sends the Webhook"] --> B["Application receives the event"]
    B --> C["Query the database"]
    C --> D["Database unavailable"]
    D --> E["Unhandled exception thrown"]
    E --> F["Return HTTP 500"]
    F --> G["Event enters retry"]

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

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

The HTTP 500 confirms that the request reached the application. The investigation should start from the error generated during processing.

How to investigate

1. Check the Webhook Logs

Find the attempt with HTTP 500 in Webhook Logs.

Use the attempt time and the payload sent to find the same request in your application logs.

2. Check the application logs

Look for the exception recorded at the same time as the attempt.

Common examples:

NullReferenceException

Database connection timeout

SQL syntax error

Connection refused

Out of memory

The cause of the 500 must be fixed in the application or in the dependency that caused the failure.

3. Check the payload handling

Confirm that the parser accepts:

• optional fields;
• null values;
• attributes not yet used by the application.

Do not reject the event just because the payload received a new attribute.

4. Check the dependencies

Confirm the availability and behavior of the services used during processing:

• database;
• Redis;
• RabbitMQ;
• internal queues;
• external APIs;
• authentication services;
• email services.

If any of these dependencies can delay or interrupt the request, move the processing to an asynchronous step whenever possible.

5. Reproduce the error

Use Postman or another HTTP tool to send your application the same payload recorded in the Webhook Logs.

If the endpoint returns 500 again, use the local logs to identify the step that generated the exception.

Fix the processing flow

Avoid running the entire business rule before confirming receipt of the event.

The recommended flow is:

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Receive the event"] --> B["Persist the event"]
    B --> C["Return HTTP 200"]
    C --> D["Process in the background"]
    D --> E["Run business rules"]

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

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

Persist the id before processing to support resends without running the same business rule more than once.

See how to implement idempotency in Webhooks.

What happens while the error persists

The HTTP 500 does not confirm delivery of the event.

While the failures continue:

• the event may be resent;
• the configuration enters the progressive penalty mechanism;
• after 15 consecutive failures, the Webhook queue is interrupted;
• new events continue to be stored;
• pending events remain available for up to 14 days.

Understand Queue penalty.

How to validate the fix

After fixing the application:

1. reproduce the payload that caused the error and confirm the endpoint no longer returns 500;
2. if the queue is interrupted, reactivate the configuration;
3. generate or wait for a new event;
4. check the Webhook Logs;
5. confirm that new deliveries return HTTP 200.

After recovery, pending events are sent again according to the delivery type configured in the Webhook.

Next steps

• Check the Webhook Logs
• Review how events are received
• Implement idempotency in Webhooks
• Understand Queue penalty
• Reactivate an interrupted queue
• See other Webhook errors