Criar novo Webhook pela aplicação web

Configure manualmente um Webhook pela aplicação Asaas para enviar eventos à URL da sua integração.

Use esse fluxo quando não precisar criar ou gerenciar Webhooks programaticamente. Para provisionamento automatizado, utilize Criar novo Webhook pela API.

Antes de começar

Tenha:

uma URL pública para receber as notificações;
um endpoint preparado para receber requisições POST;
um e-mail para alertas relacionados ao Webhook;
os eventos que sua aplicação precisa receber;
o tipo de envio adequado à sua integração.

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

Como funciona

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Preparar o endpoint"] --> B["Acessar Webhooks"]
    B --> C["Criar o Webhook"]
    C --> D["Configurar URL e token"]
    D --> E["Selecionar os eventos"]
    E --> F["Salvar o Webhook"]
    F --> G["Validar o recebimento"]
    G --> H["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,G validacao
    class H sucesso

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

1. Acesse a configuração de Webhooks

Na aplicação Asaas, acesse:

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

Clique em Criar Webhook.

2. Configure o Webhook

Preencha as configurações apresentadas no formulário:

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

Consulte os Tipos de 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.

O token configurado é enviado nas notificações pelo header:

asaas-access-token

Valide esse valor no endpoint antes de processar o evento.

3. Selecione os eventos

Escolha somente os eventos que sua aplicação precisa processar.

Consulte a lista completa de Eventos de Webhooks.

Cada Webhook pode possuir seu próprio conjunto de eventos.

4. Salve e valide o Webhook

Após salvar, provoque um evento correspondente a uma das opções selecionadas e confirme se sua aplicação recebeu o POST.

Exemplo simplificado de notificação:

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

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

Após persistir o evento, responda:

HTTP/1.1 200 OK

Para a implementação completa do endpoint, consulte Receba eventos do Asaas no seu endpoint de Webhook.

Resultado esperado

O Webhook deve aparecer entre as configurações da conta e começar a receber os eventos selecionados quando eles ocorrerem.

É possível configurar até 10 Webhooks por conta, utilizando URLs e conjuntos de eventos diferentes.

Gerencie Webhooks existentes

Pela mesma área da aplicação, você pode editar ou remover Webhooks já configurados.

Para investigar falhas de entrega, utilize os Logs de Webhooks.

Como os eventos seguem o modelo at least once, implemente idempotência antes de utilizar o fluxo em Produção.

Consulte como implementar idempotência em Webhooks.

Próximos passos

Updated 6 days ago

Did this page help you?