Create new Webhook via the API

Create Webhooks programmatically for main accounts or subaccounts when your integration needs to provision and manage configurations without manual intervention.

Each account can have up to 10 Webhooks.

Before you start

Have:

• a valid API Key;
• a public URL prepared to receive POST requests;
• the events your application needs to receive;
• the send type suited to the flow;
• a secure authToken.

How it works

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Prepare the endpoint"] --> B["Select the events"]
    B --> C["Define the send type"]
    C --> D["Create the Webhook"]
    D --> E["Store the ID"]
    E --> F["Validate receipt"]
    F --> G["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 validacao
    class G sucesso

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

1. Define the events

In events, provide only the events your integration needs.

See the Webhook Events.

2. Define the send type

The sendType field accepts:

• SEQUENTIALLY — preserves the sending order;
• NON_SEQUENTIALLY — allows parallel deliveries without an order guarantee.

See the Send types.

3. Define the authToken

The authToken will be sent in every notification in the header:

asaas-access-token

4. Create the Webhook

Use:

POST /v3/webhooks

Example:

{
  "name": "Payments Webhook",
  "url": "https://www.suaaplicacao.com.br/webhooks/asaas",
  "email": "[email protected]",
  "enabled": true,
  "interrupted": false,
  "apiVersion": 3,
  "authToken": "secure-token-with-more-than-32-characters",
  "sendType": "SEQUENTIALLY",
  "events": [
    "PAYMENT_RECEIVED",
    "PAYMENT_OVERDUE"
  ]
}

The fields used in this example have the following purposes:

See the Create new Webhook endpoint.

Expected result

The API returns the created Webhook with a unique identifier in id.

Store this ID to retrieve, update or remove the configuration later.

5. Validate receipt

After creating the Webhook, trigger one of the configured events and confirm that your application received the POST request.

The receiving endpoint implementation must handle:

• validation of the asaas-access-token;
• event persistence;
• idempotence;
• the response to Asaas;
• asynchronous processing.

See how to receive Asaas events at your Webhook endpoint.

Manage Webhooks via the API

After creation, use the management endpoints as needed:

Use these requests to manage the Webhook configuration, not to track changes to API resources. To synchronize charges, transfers, subscriptions and other resources, process the events you receive.

Next steps

• Implement event receiving
• Implement idempotence
• Learn about the Webhook Events
• Choose the send type
• Monitor the Webhook Logs