DiscordStatus
Guias / Guides

Create a new Webhook through the API

You can create Webhooks programmatically through the Asaas API, both for main accounts and subaccounts.

This approach is recommended for integrations that need to create, update, or manage Webhooks automatically, without relying on manual configuration through the web application.

Each account can have up to 10 Webhooks, and each Webhook can be configured to receive only the events required for the operation.

When to use

Creation through the API is recommended when:

  • your platform creates accounts or subaccounts automatically;
  • it is necessary to provision Webhooks without manual intervention;
  • different customers need independent configurations;
  • you want to automate the Webhook activation process;
  • the integration needs to manage Webhooks dynamically.

Requirements

Before creating a Webhook through the API, you need:

  • an active Asaas account;
  • a valid API Key;
  • a publicly accessible URL;
  • an application capable of receiving HTTP POST requests;
  • to define which events will be monitored;
  • to ensure that the endpoint correctly responds to notifications.
📘

Important

The configured endpoint must be prepared to process notifications sent by Asaas and return HTTP responses in the 2xx range.

Creating a new Webhook

To create a Webhook, use the endpoint:

POST /v3/webhooks
See the complete reference for this endpoint

Example:

{
    "name": "Example Name",
    "url": "https://www.example.com/webhook/asaas",
    "email": "[email protected]",
    "enabled": true,
    "interrupted": false,
    "authToken": "whsec_Pxeh17yy3LQbLVpnzz6I1chB7mtzYk5F7pg8bRR80pE",
    "sendType": "SEQUENTIALLY",
    "events": [
        "PAYMENT_CREDIT_CARD_CAPTURE_REFUSED",
        "PAYMENT_CHECKOUT_VIEWED",
        "PAYMENT_BANK_SLIP_VIEWED",
        "PAYMENT_DUNNING_REQUESTED",
        "PAYMENT_DUNNING_RECEIVED",
        "PAYMENT_AWAITING_CHARGEBACK_REVERSAL",
        "PAYMENT_CHARGEBACK_DISPUTE",
        "PAYMENT_CHARGEBACK_REQUESTED",
        "PAYMENT_RECEIVED_IN_CASH_UNDONE",
        "PAYMENT_REFUND_IN_PROGRESS",
        "PAYMENT_REFUNDED",
        "PAYMENT_RESTORED",
        "PAYMENT_DELETED",
        "PAYMENT_OVERDUE",
        "PAYMENT_ANTICIPATED",
        "PAYMENT_RECEIVED",
        "PAYMENT_CONFIRMED",
        "PAYMENT_UPDATED",
        "PAYMENT_CREATED",
        "PAYMENT_REPROVED_BY_RISK_ANALYSIS",
        "PAYMENT_APPROVED_BY_RISK_ANALYSIS",
        "PAYMENT_AWAITING_RISK_ANALYSIS",
        "PAYMENT_AUTHORIZED"
    ]
}

In the example above, the Webhook was configured to receive virtually all payment-related events.

Important parameters

Some attributes directly influence Webhook behavior:

FieldPurpose
urlEndpoint that will receive events
enabledDefines whether the Webhook is active
interruptedIndicates whether the queue is interrupted
authTokenToken sent through the asaas-access-token header
sendTypeDefines delivery behavior
eventsList of events to be monitored
emailAddress used for failure alerts
📘

Recommended

Configure only the events that are actually required to avoid unnecessary processing.

Authentication token (authToken)

🚧

Secure token

The token must follow minimum security requirements:

  • contain between 32 and 255 characters;
  • not contain blank spaces;
  • not use simple sequences;
  • not use an Asaas API Key.

If the field is not provided, Asaas will automatically generate a secure value.

📘

Important

The token value is returned only when the Webhook is created.

Make sure to store it securely, as it will be required to validate incoming requests.

How it works after creation

Once created, the flow usually occurs as follows:

An event occurs
↓
Asaas identifies configured Webhooks
↓
The event is sent to the registered URL
↓
Application processes the event
↓
Endpoint returns HTTP 2xx
↓
The event is considered delivered

Important behaviors

When using Webhooks through the API, consider that:

  • notifications are sent through HTTP POST requests;
  • delivery follows the at least once model;
  • the same event may be sent more than once;
  • implementing idempotency is recommended;
  • failures may trigger new delivery attempts;
  • after 15 consecutive failures, the queue may be interrupted;
  • events remain stored for up to 14 days.

Example of a received event

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

The structure of the object sent varies according to the event type.

Common errors and best practices

  • Endpoint returning errors:

Responses outside the 2xx range may trigger new delivery attempts.

  • Invalid token:

Validate the asaas-access-token header to ensure the request was sent by Asaas.

  • Duplicate events:

Implement idempotency to avoid repeated processing.

  • Long-running processing:

Return the HTTP response quickly and perform heavy processing asynchronously.

Operational impacts

Each account can have up to 10 Webhooks.

Endpoint failures may cause:

  • new delivery attempts;
  • queue penalties;
  • synchronization interruption;
  • permanent event loss after 14 days.

Therefore, continuous monitoring of Webhooks in production is recommended.

Webhook management

You can also:

  • Update an existing Webhook

Edit Webhook

  • Remove a Webhook

Delete Webhook

  • List Webhooks

Use:

GET /v3/webhooks
See the complete reference for this endpoint


Through this request, it is possible to verify:

  • existing Webhooks;
  • configured events;
  • whether the Webhook is active;
  • whether there is an interrupted queue.

Next steps

We recommend reviewing: