Events for Checkout

Webhooks are the best and safest way to keep your application data synchronized with Asaas Checkout events.

Whenever a relevant change occurs in the Checkout lifecycle, an event may be sent to the configured URL.

When to use

Checkout Webhooks are recommended when your application needs to:

• track checkout creation;
• identify completed payments;
• detect expired checkouts;
• identify cancellations;
• automatically synchronize orders, subscriptions, or services;
• avoid frequent polling requests.

How to configure Checkout Webhooks

The configuration uses the same default endpoint for creating Asaas Webhooks.

POST /v3/webhooks

You must send the account access token:

access_token

Example:

{
  "name": "test",
  "url": "https://my-url.com",
  "sendType": "SEQUENTIALLY",
  "email": "[email protected]",
  "enabled": true,
  "interrupted": false,
  "events": [
    "CHECKOUT_CREATED",
    "CHECKOUT_CANCELED",
    "CHECKOUT_EXPIRED",
    "CHECKOUT_PAID"
  ]
}

The endpoint used is the same as the standard Webhook configuration.

The only difference is the list of monitored events.

The available events are:

• CHECKOUT_CREATED - Checkout created.
• CHECKOUT_CANCELED - Checkout canceled.
• CHECKOUT_EXPIRED - Checkout expired.
• CHECKOUT_PAID - Checkout paid.

Important parameters

Important behaviors

At least once delivery

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

We recommend implementing idempotency using the field:

id

Retry on failure

If the application returns responses outside the HTTP 2xx family, new delivery attempts may occur.

After consecutive failures, the queue may be interrupted.

Asynchronous processing

Ideally, you should respond quickly to Asaas and process the event in the background.

Recommended flow:

Receive event
↓
Persist event
↓
Return HTTP 200
↓
Process internally

Event ordering

When configured as:

sendType = SEQUENTIALLY

events are delivered sequentially.

Example of a received request

After configuration, Asaas will send POST requests to the registered URL.

Example:

{
  "id": "evt_37260be8159d4472b4458d3de13efc2d&15370",
  "event": "CHECKOUT_CREATED",
  "dateCreated": "2024-10-31 18:07:47",
  "account": {
    "id": "47ed0d25-f9fb-4b35-b23a-d8895caf92b7",
    "ownerId": null
  },
  "checkout": {
    "id": "2bd251f0-09b2-44ff-8a0c-a5cb29e5bbda",
    "link": null,
    "status": "ACTIVE",
    "minutesToExpire": 10,
    "billingTypes": [
      "MUNDIPAGG_CIELO"
    ],
    "chargeTypes": [
      "RECURRENT"
    ],
    "callback": {
      "cancelUrl": "https://google.com",
      "successUrl": "https://google.com",
      "expiredUrl": "https://google.com"
    },
    "items": [
      {
        "name": "teste2",
        "description": "teste",
        "quantity": 2,
        "value": 100
      },
      {
        "name": "teste2",
        "description": "teste2",
        "quantity": 2,
        "value": 100
      }
    ],
    "subscription": {
      "cycle": "MONTHLY",
      "nextDueDate": "2024-10-31T03:00:00+0000",
      "endDate": "2025-10-29T03:00:00+0000"
    },
    "installment": null,
    "split": [
      {
        "walletId": "c1ad713f-77fc-45b0-b734-b2ff9970d6d8",
        "fixedValue": 2,
        "percentualValue": null,
        "totalFixedValue": null
      },
      {
        "walletId": "c1ad713f-77fc-45b0-b734-b2ff9970d6d8",
        "fixedValue": null,
        "percentualValue": 2,
        "totalFixedValue": null
      }
    ],
    "customer": "cus_000000018936",
    "customerData": null
  }
}

Important payload fields

Security

We recommend:

• validating the asaas-access-token header;
• responding quickly with HTTP 200;
• processing events asynchronously;
• implementing idempotency;
• monitoring Webhook Logs;
• allowing new attributes in the payload without throwing exceptions.

Common errors

Duplicate event

Webhooks use at least once delivery, therefore an event may be resent.

Use the id field to avoid duplicate processing.

Endpoint timeout

Long processing times may trigger new delivery attempts.

Return HTTP 200 quickly and process in the background.

HTTP 500

Internal failures prevent delivery confirmation and may interrupt the queue.

New fields in the payload

New attributes may be added in the future.

The application should ignore unknown fields.

Operational impacts

Integration failures may cause:

• new delivery attempts;
• synchronization queue interruption;
• duplicate events;
• inconsistencies between systems;
• permanent event loss after 14 days.

🚧

Attention

• As new products and features are introduced in Asaas, new attributes may be added to the Webhook. It is very important that your code is prepared not to throw exceptions if Asaas returns new attributes not handled by your application, as this may cause synchronization queue interruption.
• We will send an email and notify our Discord whenever new fields are added to the Webhook. Notifications will be sent to the email address configured in the Webhook settings.