Webhooks

Os Webhooks são o mecanismo utilizado pelo Asaas para notificar automaticamente sistemas externos sempre que determinados eventos ocorrerem na conta.

Em vez de realizar consultas frequentes à API para verificar alterações, sua aplicação pode receber notificações em tempo real sempre que eventos como pagamentos, assinaturas, transferências, Pix, notas fiscais ou outros recursos forem atualizados.

Os Webhooks permitem construir integrações mais eficientes, reduzir consultas desnecessárias e manter diferentes sistemas sincronizados automaticamente.

Quando utilizar

Os Webhooks são recomendados para integrações que precisam:

• receber notificações em tempo real;
• sincronizar informações automaticamente;
• atualizar pedidos, clientes ou serviços após pagamentos;
• acompanhar eventos relacionados a cobranças, assinaturas e Pix;
• reduzir a necessidade de consultas constantes à API;
• implementar arquiteturas orientadas a eventos.

Esse modelo é indicado para a maioria das integrações em produção.

Como funciona

De forma simplificada, o fluxo ocorre da seguinte maneira:

Evento ocorre na conta Asaas
↓
Asaas identifica os webhooks configurados
↓
Notificação é enviada para a URL da aplicação
↓
Sistema recebe o evento
↓
Evento é processado
↓
Integração atualiza seus dados

Cada notificação contém informações relacionadas ao recurso que originou o evento.

Fluxo recomendado

Uma implementação típica costuma seguir a seguinte jornada:

Criar Webhook
↓
Configurar endpoint da aplicação
↓
Selecionar eventos monitorados
↓
Receber notificações
↓
Implementar idempotência
↓
Monitorar logs
↓
Tratar falhas e filas interrompidas

Conceitos importantes

Durante a implementação, alguns conceitos merecem atenção:

• os eventos são enviados para uma URL configurada pela integração;
• falhas no processamento podem provocar novas tentativas de envio;
• retornos diferentes de sucesso podem ocasionar penalização da fila;
• a implementação deve ser idempotente para evitar processamentos duplicados;
• mecanismos de firewall podem bloquear as requisições do Asaas;
• os logs permitem acompanhar falhas e tentativas de entrega.

Conteúdos desta seção

Esta seção reúne conteúdos relacionados à implementação e operação dos Webhooks:

Primeiros passos

• Introdução
• Criar novo Webhook pela aplicação web
• Criar novo Webhook pela API
• Receba eventos do Asaas no seu endpoint de Webhook

Boas práticas

• Como implementar idempotência em Webhooks
• Polling vs. Webhooks
• Tipos de envio

Eventos disponíveis

• Eventos de Webhooks
• Eventos para cobranças
• Eventos para assinaturas
• Eventos para notas fiscais
• Eventos para transferências
• Eventos para Pix Automático
• E outros recursos da API

Monitoramento e troubleshooting

• Logs de Webhooks
• Penalização de filas
• Fila pausada
• Como reativar fila interrompida
• Erros 400, 403, 404, 408, 500 e outros

Infraestrutura e segurança

• Bloqueio do Firewall na Cloudflare
• IPs oficiais do Asaas

Perguntas frequentes

• FAQ de Webhooks

Boas práticas

• Utilize Webhooks sempre que possível em vez de consultas periódicas.
• Implemente processamento idempotente.
• Monitore os logs da integração.
• Garanta que a aplicação responda adequadamente às notificações.
• Valide periodicamente os eventos configurados.
• Monitore filas interrompidas e penalizações.

Próximos passos

Se você está iniciando uma integração baseada em eventos, recomendamos seguir a seguinte sequência:

1. Introdução.
2. Criar um Webhook.
3. Receber eventos no endpoint.
4. Implementar idempotência.
5. Conhecer os eventos disponíveis.
6. Configurar monitoramento e tratamento de falhas.