When activating a Webhook, every time there are changes in the integrated resources of the configured events, a POST request will be made to the configured address, containing the event and the involved resource.

Enabling a Webhook

To activate Webhooks, you must access the Asaas Integrations area, under the Webhooks tab, and provide the URL of your application that should receive the POST from Asaas. You can also configure Webhooks via API. Check the guides:

• Create a new Webhook through the web application
• Create a new Webhook through the API

Webhooks best practices

Use these practices to ensure your integration with Webhooks is secure and works properly.

Manage duplicate events

Webhooks guarantee "at least once" delivery. This means your endpoint may occasionally receive the same webhook event more than once. You can ignore duplicate events using idempotence. One way is to log the events you've processed and not to record them again.

Configure only the necessary events for your application

Configure only the necessary events for your application in each Webhook. Receiving additional events (or all events) overloads your server and is not recommended.

Manage events asynchronously

You may encounter scalability issues if you opt for synchronous events or have host overload problems in case of event spikes at endpoints, so it's best to configure event queue processing asynchronously.

Verify that events were sent by Asaas

You have the option to use a token to authenticate requests coming from Asaas. This token can be provided in the Webhook configuration. The informed token will be sent in all notifications in the asaas-access-token header.

Return a 200 response as quickly as possible

For Asaas to consider the notification as successfully processed, the HTTP status of the response must be 200. Synchronization is done every time there is a change in events, and if your system fails to respond HTTP 200 15 consecutive times, the synchronization queue will be interrupted. New notifications continue to be generated and included in the sync queue, but they are not sent to your application. After ensuring that your system will respond HTTP 200 to Asaas, just reactivate the sync queue by accessing My Account area, Integration tab, and all pending events will be processed in chronological order.

Be aware of potential communication failures

If your application returns any HTTP response other than 200, your event queue will be interrupted, and you will receive a communication from Asaas to notify you, be attentive to avoid having event synchronization issues.

❗️

Attention

• Asaas keeps Webhook events for 14 days. You will receive an email if there is any communication problem and your Webhooks stop working.
• If your queue is paused, it's extremely important that you resolve any issues to avoid losing important information.
• Events that have been stopped in the queue for more than 14 days will be permanently deleted.