Understand how Webhooks work

A Webhook allows Asaas to notify your application when an event occurs.

Asaas sends a POST request to the configured URL with the event type and the data of the related resource. This way, your application can react to changes without repeatedly querying the API.

Why use Webhooks?

Webhooks are recommended when your application needs to track state changes automatically, such as payments received, transfers, subscriptions or changes in other resources.

Instead of periodically querying an endpoint to find out whether something changed, your application receives the update when the event occurs.

To compare the two models, see Polling vs. Webhooks.

How delivery works

The basic flow is:

Event occurs in Asaas
↓
Asaas sends a POST to the configured URL
↓
Your application receives and persists the event
↓
Endpoint responds HTTP 200
↓
Event is processed by the application

Each Webhook receives only the events selected in its configuration.

You can register up to 10 Webhooks per account, using different URLs and sets of events.

Event structure

The payload indicates which event occurred and includes the related resource.

Example:

{
  "id": "evt_123456789",
  "event": "PAYMENT_RECEIVED",
  "dateCreated": "2026-06-19 14:30:00",
  "payment": {
    "object": "payment",
    "id": "pay_080225913252",
    "customer": "cus_000005913252",
    "value": 150.00,
    "netValue": 148.35,
    "billingType": "PIX",
    "status": "RECEIVED"
  }
}

The id field identifies the event and must be used to avoid duplicate processing.

See the Webhook Events.

Handle duplicate events

Webhooks use the at least once delivery model. This means the same event may be sent more than once.

Persist the received id and do not run the business rule again if this identifier has already been processed.

See how to implement idempotence in Webhooks.

Respond to Asaas

After persisting the event, respond:

HTTP/1.1 200 OK

Then run time-consuming processing asynchronously.

This approach reduces the risk of timeouts and prevents a slow operation from blocking the receipt of the next notifications.

See how to receive events at your Webhook endpoint.

Validate the origin of notifications

In the Webhook configuration, you can define an authentication token.

Asaas sends this value in every notification in the header:

asaas-access-token

Validate the header before processing the event.

Do not use an Asaas API Key as the Webhook authToken.

Understand the behavior in case of failure

When a delivery fails, Asaas retries it.

After 15 consecutive failures, the Webhook queue may be interrupted. New events continue to be generated, but they are no longer sent until the queue is reactivated.

Use the Webhook Logs to identify failures and see Paused queue to understand the behavior and how to recover.

Choose how to create the Webhook

You can configure Webhooks in two ways:

Before creating it, also define whether your integration needs to preserve the order of events.

See the Send types.

Next steps

• Create a Webhook via the web application
• Create a Webhook via the API
• Implement event receiving
• Implement idempotence
• Choose the events you need
• Choose the send type