Create new Webhook via the web application

Manually configure a Webhook through the Asaas application to send events to your integration's URL.

Use this flow when you do not need to create or manage Webhooks programmatically. For automated provisioning, use Create new Webhook via the API.

Before you start

Have:

• a public URL to receive notifications;
• an endpoint prepared to receive POST requests;
• an email address for Webhook-related alerts;
• the events your application needs to receive;
• the send type suited to your integration.

How it works

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Prepare the endpoint"] --> B["Access Webhooks"]
    B --> C["Create the Webhook"]
    C --> D["Configure URL and token"]
    D --> E["Select the events"]
    E --> F["Save the Webhook"]
    F --> G["Validate receipt"]
    G --> H["Monitor the logs"]

    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,D,E,F,G validacao
    class H sucesso

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

1. Access the Webhook settings

In the Asaas application, go to:

User menu > Integrations > Webhooks

Click Criar Webhook (Create Webhook).

2. Configure the Webhook

Fill in the settings shown in the form:

See the Send types.

The configured token is sent in notifications through the header:

asaas-access-token

Validate this value in the endpoint before processing the event.

3. Select the events

Choose only the events your application needs to process.

See the complete list of Webhook Events.

Each Webhook can have its own set of events.

4. Save and validate the Webhook

After saving, trigger an event corresponding to one of the selected options and confirm that your application received the POST.

Simplified notification example:

{
  "event": "PAYMENT_RECEIVED",
  "payment": {
    "id": "pay_080225913252",
    "status": "RECEIVED",
    "value": 150.00
  }
}

After persisting the event, respond:

HTTP/1.1 200 OK

For the complete endpoint implementation, see Receive Asaas events at your Webhook endpoint.

Expected result

The Webhook should appear in the account settings and start receiving the selected events when they occur.

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

Manage existing Webhooks

From the same area of the application, you can edit or remove Webhooks that are already configured.

To investigate delivery failures, use the Webhook Logs.

Since events follow the at least once model, implement idempotence before using the flow in Production.

See how to implement idempotence in Webhooks.

Next steps

• Implement event receiving
• Implement idempotence
• Learn about the Webhook Events
• Choose the send type
• Monitor the Webhook Logs
• Create Webhooks via the API