Polling vs. Webhooks

Let's say a customer accesses your website/application and makes a purchase. Your purchasing service receives a request, which sends it to the payment service, which then calls the Asaas payment gateway, correct?

After that, there are two ways to receive information from Asaas:

Polling

After creating a payment, your application repeatedly sends requests to Asaas to check the payment status until Asaas returns that the payment has been completed.

However, this approach has some drawbacks. Polling consumes resources both on your application side and on the Asaas side. It can even cause your API key to be blocked by quota limits.

Polling example

Application creates payment
↓
GET /v3/payments/{id}
↓
GET /v3/payments/{id}
↓
GET /v3/payments/{id}
↓
Payment confirmed

The shorter the interval between requests, the higher the resource consumption and the number of API calls.

Webhooks

Webhooks are essentially a "notify me back at this URL when there are updates to this payment" mechanism. When Asaas finishes processing a payment, your configured URL will receive the corresponding status.

This changes the paradigm, and your payment service no longer needs to spend resources checking the status of a payment.

Example flow using Webhooks

Application creates payment
↓
Payment is processed
↓
Event occurs
↓
Asaas sends POST to your endpoint
↓
Application receives the notification
↓
Returns HTTP 200

Endpoint example

POST https://api.example.com/webhooks/asaas

Payload example

{
  "id": "evt_05b708f961d739ea7eba7e4db318f621",
  "event": "PAYMENT_RECEIVED",
  "payment": {
    "id": "pay_080225913252"
  }
}

Important parameters and behaviors

When using Webhooks, it is important to consider:

Some useful tips when using Webhooks:

• You should develop an API on your side responsible for receiving Webhook requests;
• It is recommended to create security rules in your endpoint. Asaas allows you to define an authToken for each Webhook, for example;
• If any communication issue occurs with your API, the queue is interrupted and you will receive a notification email.

Common errors and best practices

Duplicate events

Webhooks follow the at least once delivery model, which means the same event may be delivered more than once.

Implement idempotency to avoid duplicate processing.

Slow endpoint

If the application takes too long to respond, additional delivery attempts may occur.

Ideally, events should be processed asynchronously and HTTP 200 should be returned quickly.

Communication failures

After several consecutive failures, the queue may be interrupted.

It is recommended to monitor the Webhook Logs and quickly resolve any availability issues.

Security

Use the following header:

asaas-access-token

and, if possible, restrict requests to the official Asaas IP addresses.

Operational impacts

Besides saving resources, Webhooks ensure that your application receives an event whenever something changes in the gateway.

Polling may work for checking whether a payment has been completed, but it will not proactively notify you about situations such as overdue invoices or when a credit card payment has actually settled into your account.

In addition, polling increases API consumption and can lead to unnecessary resource usage in your application.

Using Webhooks is the most practical and secure way to keep your application updated about everything happening in the Asaas gateway.

Next steps

After configuring Webhooks, we recommend reviewing:

• Receive events from Asaas in your Webhook endpoint;
• How to implement idempotency in Webhooks;
• Webhook events;
• Delivery types;
• Webhook logs;
• Queue penalties;
• Paused queue.