Criar novo Webhook pela aplicação web

Os Webhooks também podem ser configurados diretamente pela interface do Asaas, sem necessidade de utilizar a API.

Essa opção é recomendada para integrações que desejam configurar, editar e gerenciar Webhooks manualmente através da aplicação web.

Quando utilizar

A configuração pela aplicação web é indicada quando:

a criação dos Webhooks é realizada manualmente;
a integração possui poucos endpoints;
é necessário ativar ou desativar Webhooks rapidamente;
deseja-se monitorar e editar configurações existentes;
não existe necessidade de automatizar a criação dos Webhooks via API.

Antes de começar

Antes de criar um Webhook, é necessário:

possuir uma conta Asaas ativa;
possuir uma URL acessível pela internet;
possuir uma aplicação capaz de receber requisições HTTP POST;
definir quais eventos deverão ser monitorados;
garantir que o endpoint consiga retornar respostas HTTP da família 2xx.

📘
Importante
Os Webhooks enviam notificações através de requisições HTTP POST. O endpoint configurado deve estar preparado para processar essas chamadas.

Você pode criar novos Webhooks utilizando a aplicação web do Asaas.

Para isso, acesse:

Menu do usuário > Integrações > Webhooks

Ao clicar em Criar Webhook, será exibido um formulário.

Na primeira etapa é necessário informar:

nome do Webhook;
URL responsável pelo recebimento dos eventos;
e-mail para comunicação de falhas;
versão da API;
token de autenticação;
status da fila de sincronização;
status do Webhook;
tipo de envio.

Confira também os tipos de envio disponíveis.

Configurações importantes

Configuração	Finalidade
Nome	Identifica o Webhook
URL	Endpoint que receberá os eventos
E-mail	Recebe notificações relacionadas a falhas
API Version	Define a versão utilizada
Auth Token	Permite validar a origem das notificações
Enabled	Ativa ou desativa o Webhook
Interrupted	Controla a fila de sincronização
Send Type	Define o comportamento do envio

🚧
Token de autenticação seguro
O token deve:

possuir entre 32 e 255 caracteres;

não conter espaços em branco;

evitar sequências simples;

não utilizar uma API Key do Asaas.

O botão Gerar token cria automaticamente um valor seguro.

Seleção dos eventos

Após configurar o Webhook, selecione quais eventos deverão gerar notificações.

É possível receber eventos relacionados a:

cobranças;
assinaturas;
Pix;
transferências;
notas fiscais;
Checkout;
movimentações internas;
e diversos outros recursos.

Consulte a lista completa de eventos.

Fluxo de funcionamento

Após a configuração, o comportamento padrão é:

Evento ocorre na conta
↓
Asaas identifica os Webhooks configurados
↓
Notificação é enviada para a URL
↓
Aplicação processa o evento
↓
Endpoint retorna sucesso
↓
Evento é considerado entregue

Exemplo de notificação

As notificações são enviadas através de requisições HTTP POST.

Exemplo:

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

📘
Importante
O formato do objeto enviado varia conforme o evento configurado.

Regras importantes

É possível possuir até 10 Webhooks por conta.
Cada Webhook pode monitorar eventos diferentes.
Os eventos são enviados através de requisições POST.
O modelo de entrega é at least once, portanto o mesmo evento pode ser enviado mais de uma vez.
Recomenda-se implementar idempotência para evitar processamentos duplicados.
Os eventos permanecem armazenados por até 14 dias.
Caso ocorram 15 falhas consecutivas, a fila poderá ser interrompida.

Resposta esperada da aplicação

Para que a entrega seja considerada bem-sucedida, a aplicação deve retornar uma resposta HTTP da família 2xx.

Exemplos:

HTTP/1.1 200 OK

HTTP/1.1 204 No Content

Respostas diferentes podem provocar novas tentativas de entrega.

Comportamentos importantes

Ao utilizar Webhooks, considere que:

a entrega dos eventos é assíncrona;
eventos podem ser reenviados em caso de falha;
falhas consecutivas podem interromper a fila;
eventos pendentes permanecem armazenados por até 14 dias;
após a reativação da fila, os eventos são reenviados em ordem cronológica;
o endpoint deve responder rapidamente para evitar timeouts.

Boas práticas

Configure apenas os eventos necessários.
Utilize um token de autenticação forte.
Implemente idempotência.
Processe os eventos de forma assíncrona.
Monitore os logs do Webhook.
Evite processamentos demorados antes de responder ao Asaas.
Retorne respostas HTTP 2xx o mais rapidamente possível.

Impactos operacionais

Um Webhook ativo pode executar sincronizações automáticas entre sistemas.

Falhas no endpoint podem ocasionar:

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

Por esse motivo, recomenda-se monitorar continuamente a integração.

Você poderá ter até 10 Webhooks configurados por conta, sem restrições de URLs.

Também é possível editar ou remover Webhooks já criados.

Próximos passos

Após criar o Webhook, recomendamos consultar: