Criar novo Webhook pela API

Crie Webhooks programaticamente para contas principais ou subcontas quando sua integração precisar provisionar e gerenciar configurações sem intervenção manual.

Cada conta pode possuir até 10 Webhooks.

Antes de começar

Tenha:

uma API Key válida;
uma URL pública preparada para receber requisições POST;
os eventos que sua aplicação precisa receber;
o tipo de envio adequado ao fluxo;
um authToken seguro.

📘
Importante
O endpoint configurado deve estar preparado para processar notificações enviadas pelo Asaas e retornar respostas HTTP da família 2xx.

Como funciona

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Preparar o endpoint"] --> B["Selecionar os eventos"]
    B --> C["Definir o tipo de envio"]
    C --> D["Criar o Webhook"]
    D --> E["Armazenar o ID"]
    E --> F["Validar o recebimento"]
    F --> G["Monitorar os 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. Defina os eventos

Informe em events somente os eventos necessários para sua integração.

📘
Recomendado
Configure apenas os eventos realmente necessários para evitar processamento desnecessário.

Consulte os Eventos de Webhooks.

2. Defina o tipo de envio

O campo sendType aceita:

SEQUENTIALLY — preserva a ordem de envio;
NON_SEQUENTIALLY — permite entregas em paralelo sem garantia de ordem.

Consulte os Tipos de envio.

3. Defina o `authToken`

O authToken será enviado em todas as notificações no header:

asaas-access-token

🚧
Token seguro
O token deve seguir requisitos mínimos de segurança:

possuir entre 32 e 255 caracteres;

não conter espaços em branco;

não utilizar sequências simples;

não utilizar uma API Key do Asaas.

📘
Importante
O valor do token é retornado apenas no momento da criação do Webhook.
Certifique-se de armazená-lo em local seguro, pois ele será necessário para validar as requisições recebidas.

4. Crie o Webhook

Utilize:

POST /v3/webhooks

Exemplo:

{
  "name": "Webhook de pagamentos",
  "url": "https://www.suaaplicacao.com.br/webhooks/asaas",
  "email": "[email protected]",
  "enabled": true,
  "interrupted": false,
  "apiVersion": 3,
  "authToken": "token-seguro-com-mais-de-32-caracteres",
  "sendType": "SEQUENTIALLY",
  "events": [
    "PAYMENT_RECEIVED",
    "PAYMENT_OVERDUE"
  ]
}

Os campos utilizados neste exemplo têm as seguintes funções:

Campo	Função
`name`	Identifica o Webhook
`url`	Define o endpoint que receberá os eventos
`email`	Define o e-mail para comunicações do Webhook
`enabled`	Define se o Webhook está ativo
`interrupted`	Define o estado da fila de sincronização
`apiVersion`	Define a versão da API
`authToken`	Autentica as notificações recebidas
`sendType`	Define o comportamento do envio
`events`	Define quais eventos serão enviados

Consulte o endpoint Criar novo webhook.

Resultado esperado

A API retorna o Webhook criado com um identificador único em id.

Armazene esse ID para consultar, atualizar ou remover a configuração posteriormente.

5. Valide o recebimento

Após criar o Webhook, provoque um dos eventos configurados e confirme se sua aplicação recebeu a requisição POST.

A implementação do endpoint receptor deve tratar:

validação do asaas-access-token;
persistência do evento;
idempotência;
resposta ao Asaas;
processamento assíncrono.

Consulte como receber eventos do Asaas no seu endpoint de Webhook.

Gerencie os Webhooks pela API

Após a criação, utilize os endpoints de gerenciamento conforme a necessidade:

Ação	Endpoint	Referência
Listar configurações	`GET /v3/webhooks`	Listar webhooks
Atualizar configuração	`PUT /v3/webhooks/{id}`	Atualizar webhook existente
Remover configuração	`DELETE /v3/webhooks/{id}`	Remover um webhook

Use essas consultas para gerenciar a configuração dos Webhooks, não para acompanhar mudanças dos recursos da API. Para sincronização de cobranças, transferências, assinaturas e outros recursos, processe os eventos recebidos.

Próximos passos

Updated 14 days ago

Did this page help you?

Antes de começar

Importante

Como funciona

1. Defina os eventos

Recomendado

2. Defina o tipo de envio

3. Defina o authToken

Token seguro

Importante

4. Crie o Webhook

Resultado esperado

5. Valide o recebimento

Gerencie os Webhooks pela API

Próximos passos

3. Defina o `authToken`