Webhooks FAQ

This page gathers quick answers about Webhook delivery, retries, idempotency, event order, security, and troubleshooting.

If this is your first integration, first see Introduction - Webhooks and the guide Receive Asaas events at your Webhook endpoint.

What HTTP code should my endpoint return?

Return HTTP 200 to confirm delivery of the event.

Any other code, including other 2xx responses, is treated as a failure and may start the retry and penalty process.

See also Paused queue and Queue penalty.

Does Asaas retry deliveries?

Yes. When a delivery fails, Asaas makes new attempts at progressive intervals.

After 15 consecutive failures, the queue for that Webhook configuration is interrupted.

While the queue is interrupted, new events continue to be generated and stored, but they are not sent until reactivation.

See Queue penalty for the intervals between attempts.

Can the same event be sent more than once?

Yes. Webhooks use the at least once delivery model, so the same event may be received more than once.

The id remains the same in redeliveries of the same event.

{
  "id": "evt_123456",
  "event": "PAYMENT_RECEIVED"
}

Use the id as the idempotency key. If evt_123456 has already been persisted, do not run the same business rule again.

See How to implement idempotency in Webhooks.

Do events arrive in the order in which they occurred?

It depends on the configured delivery type.

Sequential

Sequential delivery preserves the order of events.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["PAYMENT_CREATED"] --> B["PAYMENT_CONFIRMED"]
    B --> C["PAYMENT_RECEIVED"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    class A inicio
    class B validacao
    class C sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

Non-Sequential

With Non-Sequential delivery, events may be delivered simultaneously and there is no guarantee of order between different notifications.

See Delivery types to choose the right behavior for your integration.

Should I finish all processing before responding?

No. Persist the event, confirm receipt with HTTP 200, and run the business rule in the background.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Receive the Webhook"] --> B["Persist the event"]
    B --> C["Return HTTP 200"]
    C --> D["Process asynchronously"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    class A inicio
    class B,C validacao
    class D sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

Only return HTTP 200 after confirming that the event has been persisted. This lets you process the business rule later without depending on a new delivery.

What is the maximum response time?

Asaas waits up to 10 seconds for the endpoint's response.

If this time is exceeded, the attempt is considered a failure.

See Error 408 - Read Timed Out.

How long are events stored?

Pending events remain stored for up to 14 days.

If a queue remains interrupted, the oldest events that exceed this period will be permanently removed.

See Paused queue.

Where can I check delivery failures?

In the Integrations menu, go to Webhook Logs.

The logs let you check information such as:

• the HTTP code returned;
• the date and time of the attempt;
• the payload sent;
• the error message;
• the delivery status.

See Webhook Logs.

Does Asaas send a Bearer Token in Webhooks?

No. Webhooks do not use standard authentication with a Bearer Token or Basic Auth.

To validate notifications, configure an authToken in the Webhook. The value is sent in every notification in the header:

asaas-access-token

Do not use an Asaas API Key as the authToken.

See Create a new Webhook via the API for the token requirements.

Does Asaas follow HTTP redirects?

No.

The following responses are not followed automatically:

• 301;
• 302;
• 307;
• 308.

Configure the Webhook with the final URL that will respond directly to the POST request.

See Other errors.

Which Content-Type is used?

Events are sent as JSON:

Content-Type: application/json

Your endpoint must accept and parse this format.

How do I interpret the most common errors?

For other HTTP codes, see Other errors.

Can I restrict the endpoint to Asaas IPs?

Yes. If your infrastructure uses origin restrictions, configure an allowlist with the official IPs used by Webhooks in Production.

See Official Asaas IPs.

If you use Cloudflare, also see CloudFlare Firewall Blocking.

Is there a difference between Sandbox and Production?

Yes. In Sandbox there may be additional IPs used to send Webhooks.

If you use Firewall or WAF rules, validate both environments separately. Do not consider the Production IP list a guarantee of Sandbox coverage.

See Official Asaas IPs.

How do I validate that the integration is working correctly?

Check that:

• deliveries return HTTP 200;
• the Webhook queue is active;
• there are no recurring failures in the Webhook Logs;
• redeliveries of the same id do not run the business rule again;
• receiving is decoupled from long-running processing;
• the endpoint and its dependencies are monitored.

Next steps

• Understand how Webhooks work
• Create a Webhook via the web application
• Create a Webhook via the API
• Implement event receiving
• Implement idempotency
• Monitor the Webhook Logs