Criar novo Webhook pela API

Você pode criar Webhooks programaticamente através da API do Asaas, tanto para contas principais quanto para subcontas.

Essa abordagem é indicada para integrações que precisam criar, atualizar ou gerenciar Webhooks automaticamente, sem depender da configuração manual pela aplicação web.

Cada conta pode possuir até 10 Webhooks, e cada Webhook pode ser configurado para receber apenas os eventos necessários para a operação.

Quando utilizar

A criação via API é recomendada quando:

• sua plataforma cria contas ou subcontas automaticamente;
• é necessário provisionar Webhooks sem intervenção manual;
• diferentes clientes precisam possuir configurações independentes;
• você deseja automatizar o processo de ativação dos Webhooks;
• a integração precisa gerenciar Webhooks dinamicamente.

Dependências para utilização

Antes de criar um Webhook pela API, é necessário:

• possuir uma conta Asaas ativa;
• possuir uma API Key válida;
• possuir uma URL acessível publicamente;
• possuir uma aplicação capaz de receber requisições HTTP POST;
• definir quais eventos serão monitorados;
• garantir que o endpoint responda corretamente às notificações.

📘

Importante

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

Criando um novo Webhook

Para criar um Webhook, utilize o endpoint:

POST /v3/webhooks
Confira a referência completa deste endpoint

Exemplo:

{
    "name": "Nome Exemplo",
    "url": "https://www.exemplo.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"
    ]
}

No exemplo acima, o Webhook foi configurado para receber praticamente todos os eventos relacionados a cobranças.

Parâmetros importantes

Alguns atributos influenciam diretamente o comportamento do Webhook:

📘

Recomendado

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

Token de autenticação (authToken)

🚧

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.

Caso o campo não seja enviado, o Asaas gerará automaticamente um valor seguro.

📘

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.

Como funciona após a criação

Após ser criado, o fluxo normalmente ocorre da seguinte maneira:

Evento ocorre
↓
Asaas identifica os Webhooks configurados
↓
Evento é enviado para a URL cadastrada
↓
Aplicação processa o evento
↓
Endpoint retorna HTTP 2xx
↓
Evento é considerado entregue

Comportamentos importantes

Ao utilizar Webhooks via API, considere que:

• as notificações são enviadas através de requisições HTTP POST;
• a entrega segue o modelo at least once;
• o mesmo evento pode ser enviado mais de uma vez;
• recomenda-se implementar idempotência;
• falhas podem gerar novas tentativas de envio;
• após 15 falhas consecutivas, a fila poderá ser interrompida;
• os eventos permanecem armazenados por até 14 dias.

Exemplo de evento recebido

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

O objeto enviado varia conforme o tipo do evento.

Erros comuns e boas práticas

• Endpoint retornando erro:

Respostas fora da família 2xx podem provocar novas tentativas de entrega.

• Token inválido:

Valide o header asaas-access-token para garantir que a requisição foi enviada pelo Asaas.

• Eventos duplicados:

Implemente idempotência para evitar processamentos repetidos.

• Processamentos demorados:

Retorne a resposta HTTP rapidamente e realize processamentos pesados de forma assíncrona.

Impactos operacionais

Cada conta pode possuir até 10 Webhooks.

Falhas no endpoint podem provocar:

• novas tentativas de entrega;
• penalização da fila;
• interrupção da sincronização;
• perda permanente dos eventos após 14 dias.

Por isso, recomenda-se monitorar continuamente os Webhooks em produção.

Gerenciamento dos Webhooks

Também é possível:

• Atualizar um Webhook existente

Editar Webhook

• Remover um Webhook

Excluir Webhook

• Listar Webhooks

Utilize:

GET /v3/webhooks
Confira a referência completa deste endpoint

Através dessa consulta é possível verificar:

• os Webhooks existentes;
• os eventos configurados;
• se o Webhook está ativo;
• se existe fila interrompida.

Próximos passos

Recomendamos consultar:

• Receba eventos do Asaas no seu endpoint de Webhook;
• Como implementar idempotência em Webhooks;
• Tipos de envio;
• Eventos de Webhooks;
• Logs de Webhooks;
• Penalização de filas;
• Fila pausada.