Introdução - Webhooks

Entenda como funcionam os Webhooks

Um Webhook permite que o Asaas notifique sua aplicação quando um evento ocorre.

O Asaas envia uma requisição POST para a URL configurada com o tipo do evento e os dados do recurso relacionado. Assim, sua aplicação pode reagir às mudanças sem consultar repetidamente a API.

Por que utilizar Webhooks?

Webhooks são indicados quando sua aplicação precisa acompanhar mudanças de estado automaticamente, como recebimentos, transferências, assinaturas ou alterações em outros recursos.

Em vez de consultar periodicamente um endpoint para descobrir se algo mudou, sua aplicação recebe a atualização quando o evento ocorre.

Para comparar os dois modelos, consulte Polling vs. Webhooks.

Como funciona a entrega

O fluxo básico é:

Evento ocorre no Asaas
↓
Asaas envia um POST para a URL configurada
↓
Sua aplicação recebe e persiste o evento
↓
Endpoint responde HTTP 200
↓
Evento é processado pela aplicação

Cada Webhook pode receber somente os eventos selecionados na sua configuração.

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

Estrutura de um evento

O payload informa qual evento ocorreu e inclui o recurso relacionado.

Exemplo:

{
  "id": "evt_123456789",
  "event": "PAYMENT_RECEIVED",
  "dateCreated": "2026-06-19 14:30:00",
  "payment": {
    "object": "payment",
    "id": "pay_080225913252",
    "customer": "cus_000005913252",
    "value": 150.00,
    "netValue": 148.35,
    "billingType": "PIX",
    "status": "RECEIVED"
  }
}

O campo id identifica o evento e deve ser utilizado para evitar processamento duplicado.

📘
Importante
O formato do objeto enviado varia de acordo com o tipo de evento recebido. Consulte a seção "Eventos de Webhooks" para conhecer todos os eventos disponíveis.

Consulte os Eventos de Webhooks.

Trate eventos duplicados

Os Webhooks utilizam o modelo de entrega at least once. Isso significa que um mesmo evento pode ser enviado mais de uma vez.

Persista o id recebido e não execute novamente a regra de negócio caso esse identificador já tenha sido processado.

Consulte como implementar idempotência em Webhooks.

Responda ao Asaas

Após persistir o evento, responda:

HTTP/1.1 200 OK

Depois, execute processamentos demorados de forma assíncrona.

Essa abordagem reduz o risco de timeout e evita que uma operação lenta bloqueie o recebimento das próximas notificações.

Consulte como receber eventos no seu endpoint de Webhook.

Valide a origem das notificações

Na configuração do Webhook, você pode definir um token de autenticação.

O Asaas envia esse valor em todas as notificações no header:

asaas-access-token

Valide o header antes de processar o evento.

Não utilize uma API Key do Asaas como authToken do Webhook.

Entenda o comportamento em caso de falha

Quando uma entrega falha, o Asaas realiza novas tentativas.

Após 15 falhas consecutivas, a fila do Webhook pode ser interrompida. Novos eventos continuam sendo gerados, mas deixam de ser enviados até a reativação da fila.

Use os Logs de Webhooks para identificar falhas e consulte Fila pausada para entender o comportamento e a recuperação.

❗️
Atenção

O Asaas guarda eventos de Webhooks por 14 dias. Você receberá um e-mail caso haja algum problema de comunicação e seus Webhooks pararem de funcionar.

Caso sua fila seja pausada, é de extrema importância que você resolva qualquer problema em até 14 dias para evitar perder informações importantes.

Os eventos que estiverem mais de 14 dias parados na fila serão excluídos permanentemente.

Escolha como criar o Webhook

Você pode configurar Webhooks de duas formas:

Necessidade	Como seguir
Configurar e gerenciar manualmente	Criar novo Webhook pela aplicação web
Provisionar ou gerenciar programaticamente	Criar novo Webhook pela API

Antes da criação, defina também se sua integração precisa preservar a ordem dos eventos.

Consulte os Tipos de envio.

Próximos passos

Updated 10 days ago

Did this page help you?