DiscordStatus
Guias / Guides

Error 500 (Internal Server Error)

What does it mean

The 500 (Internal Server Error) in Webhook logs indicates that Asaas successfully established a connection with your endpoint and correctly sent the request, but your application itself returned an internal error during processing.

In other words, the webhook reached your system, but an exception or unexpected error prevented the request from being processed successfully.

How it works

When an event occurs in Asaas, a POST request is sent to the configured endpoint.

If your application responds with:

  • HTTP 200: the event is considered successfully delivered;
  • any other status code (400, 403, 404, 408, 500, etc.): the attempt is considered a failure.

In the case of an HTTP 500 error, it means that the issue originated inside your own application.

When does this error occur?

The most common causes are:

  • unhandled exceptions in the code;
  • database connection failures;
  • external API unavailability;
  • authentication problems with third-party services;
  • SQL query errors;
  • memory or CPU issues;
  • incorrect deserialization of the received payload;
  • unavailable dependencies;
  • timeouts in internal calls;
  • failures in queues or workers.

Impact on the integration

As long as the endpoint keeps returning HTTP 500:

  • events will continue to be retried automatically;
  • the queue will suffer progressive penalties;
  • after 15 consecutive failures, the queue will be interrupted;
  • new events will continue to accumulate;
  • events remain stored for up to 14 days;
  • events that remain unprocessed after this period will be permanently deleted.

For this reason, it is important to resolve the issue quickly.

Common scenario example

Flow:

Asaas
↓
POST webhook
↓
Application receives event
↓
Database query
↓
Database unavailable
↓
Unhandled exception
↓
HTTP 500
↓
Webhook enters retry flow

In this case, the issue is not related to communication with Asaas, but rather to the application itself.

How to investigate

1. Check application logs

The first step is to inspect the server logs.

Common examples:

NullReferenceException
Database connection timeout
SQL syntax error
Connection refused
Out of memory

The root cause is usually recorded in the logs.

2. Validate payload handling

Over time, new attributes may be added to objects sent by Asaas.

Your code should be able to ignore unknown properties and avoid deserialization exceptions.

📘

Important

Adding new attributes to Webhooks does not represent a breaking change. Your application should be tolerant of additional fields.

3. Validate external dependencies

Check the availability of:

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

In many cases, an HTTP 500 error occurs because an intermediate dependency is unavailable.

4. Test the endpoint locally

Use Postman or another tool to send the same payload received from the webhook.

If the error occurs again, you will be able to identify the source of the exception.

Best practices

  • respond with HTTP 200 as quickly as possible;
  • process heavy tasks in the background;
  • implement exception handling;
  • record detailed logs;
  • monitor CPU, memory, and database usage;
  • avoid synchronous dependencies on external services during webhook processing;
  • implement idempotency;
  • use monitoring and alerting for your application.

Common mistakes

  • assuming the payload will never change;
  • depending on external APIs during processing;
  • not handling exceptions;
  • failing because optional fields are null;
  • not recording logs;
  • returning HTTP 500 for business-rule failures.

How to verify that it worked

After fixing the issue:

  1. Reactivate the Webhook queue.
  2. Generate a new event.
  3. Check the Asaas logs.

If everything is working properly:

  • events will start being delivered normally again;
  • HTTP 500 errors will no longer appear;
  • the queue will be processed in chronological order.

Next steps

If you continue experiencing issues, we recommend consulting: