DiscordStatus
Guias / Guides

Eventos de Webhooks

Os eventos de Webhooks permitem que sua aplicação seja notificada automaticamente sempre que ocorrer alguma alteração relevante em recursos do Asaas.

Cada evento representa uma mudança de estado em determinado produto ou funcionalidade, como cobranças, assinaturas, transferências, Checkout, notas fiscais ou Pix Automático.

Esta página centraliza as categorias de eventos disponíveis. Os detalhes de cada evento, seus nomes e comportamentos são apresentados nas páginas específicas de cada recurso.

Quando utilizar

Os eventos de Webhooks são recomendados quando sua aplicação precisa ser notificada automaticamente sobre alterações ocorridas no Asaas.

Alguns exemplos:

  • atualizar pedidos após o pagamento de uma cobrança;
  • liberar acesso após confirmação de uma assinatura;
  • sincronizar sistemas financeiros;
  • acompanhar transferências;
  • monitorar emissões de notas fiscais;
  • processar eventos do Checkout;
  • acompanhar eventos do Pix Automático.

Ao utilizar Webhooks, não é necessário consultar continuamente a API para verificar mudanças de status.

Como funciona

O fluxo de funcionamento normalmente segue a estrutura abaixo:

Evento ocorre no Asaas
↓
Webhook identifica o evento
↓
Requisição HTTP POST é enviada
↓
Sua aplicação recebe o payload
↓
Evento é processado
↓
Aplicação retorna HTTP 200

Estrutura dos eventos

Todos os Webhooks enviados pelo Asaas possuem uma estrutura semelhante:

{
  "id": "evt_05b708f961d739ea7eba7e4db318f621",
  "event": "PAYMENT_RECEIVED",
  "dateCreated": "2024-06-12 16:45:03",
  "payment": {
    "id": "pay_080225913252"
  }
}

O objeto enviado varia conforme o tipo de evento.

Comportamentos importantes

Ao trabalhar com eventos de Webhooks, é importante considerar que:

  • as notificações são enviadas através de requisições HTTP POST;
  • a entrega segue o modelo at least once, portanto um mesmo evento pode ser reenviado;
  • a aplicação deve implementar idempotência;
  • respostas HTTP fora da família 2xx geram novas tentativas de envio;
  • após diversas falhas consecutivas, a fila poderá ser interrompida;
  • eventos permanecem disponíveis por até 14 dias.

Categorias de eventos disponíveis

Navegue para as páginas específicas para visualizar os eventos disponíveis em cada categoria.

Cobranças

Assinaturas

Notas fiscais

Transferências

Pague Contas

Antecipações

Recargas de celular

Situação da conta

Checkout

Bloqueios de saldo

Movimentações internas

Chaves de API

Pix Automático

Boas práticas

  • Configure apenas os eventos realmente necessários para sua aplicação.
  • Implemente idempotência no processamento.
  • Processe os eventos de forma assíncrona.
  • Monitore os Logs de Webhooks regularmente.
  • Retorne respostas HTTP 2xx rapidamente.
  • Utilize autenticação através do header asaas-access-token.

Eventos em subcontas

🚧

Eventos em subcontas

Você pode configurar Webhooks também para suas subcontas. Para saber mais, consulte a seção sobre Subcontas.

Os eventos do Webhook sempre ficarão disponíveis na interface da conta em que foram configurados.

Além disso, é possível filtrar os eventos das subcontas diretamente pela conta principal.

Próximos passos

Após configurar os Webhooks, recomendamos consultar: