Eventos para pague contas

É possível utilizar Webhooks para que seu sistema seja notificado sobre alterações que ocorram nos pagamentos de contas.

Os eventos que o Asaas notifica são:

• BILL_CREATED - Geração de um novo pagamento de contas.
• BILL_PENDING - Pagamento de contas aguardando processamento.
• BILL_BANK_PROCESSING - Pagamento de contas em processamento bancário.
• BILL_PAID - Pagamento de contas realizado.
• BILL_CANCELLED - Pagamento de contas cancelado.
• BILL_FAILED - Pagamento de contas com falha.
• BILL_REFUNDED - Pagamento de contas estornado.

Quando utilizar

Os Webhooks de pagamento de contas são recomendados quando sua aplicação precisa acompanhar automaticamente a evolução das contas pagas através do Asaas.

Alguns exemplos:

• conciliação financeira;
• atualização de ERP;
• monitoramento de pagamentos;
• auditoria financeira;
• geração automática de comprovantes;
• sincronização com sistemas externos.

Comportamentos importantes

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

Por esse motivo, recomenda-se implementar idempotência utilizando o campo:

id

do evento recebido.

Além disso:

• respostas HTTP fora da família 2xx podem gerar novas tentativas de envio;
• a fila pode ser interrompida após falhas consecutivas;
• eventos permanecem armazenados por até 14 dias;
• novos atributos podem ser adicionados ao payload futuramente.

Fluxo comum dos eventos

Normalmente, o fluxo ocorre da seguinte maneira:

BILL_CREATED
↓
BILL_PENDING
↓
BILL_BANK_PROCESSING
↓
BILL_PAID

Em situações específicas podem ocorrer:

BILL_CREATED
↓
BILL_PENDING
↓
BILL_FAILED

ou

BILL_CREATED
↓
BILL_CANCELLED

Campos importantes

Exemplo de JSON a ser recebido [POST]

A notificação consiste em um POST contendo um JSON, conforme este exemplo:

{
    "id": "evt_05b708f961d739ea7eba7e4db318f621&368604920",
    "event": "BILL_PAID",
    "dateCreated": "2024-06-12 16:45:03",
    "account": {
        "id": "47ed0d25-f9fb-4b35-b23a-d8895caf92b7",
        "ownerId": null
    },
    "bill": {
        "object": "bill",
        "id": "f1bce822-6f37-4905-8de8-f1af9f2f4bab",
        "status": "PAID",
        "value": 29.90,
        "discount": 0.00,
        "interest": 0.00,
        "fine": 0.00,
        "identificationField": "03399.77779 29900.000000 04751.101017 1 81510000002990",
        "dueDate": "2020-01-31",
        "scheduleDate": "2020-01-31",
        "paymentDate": "2020-01-31",
        "fee": 0.00,
        "description": "Celular 01/12",
        "companyName": null,
        "transactionReceiptUrl": "https://www.asaas.com/comprovantes/00016578",
        "canBeCancelled": false,
        "failReasons": null
    }
}

👍

Retorno do Webhook com tipagem e ENUMs

Caso você queira saber qual o tipo de cada campo e os retornos de ENUMs disponíveis, confira a resposta 200 no endpoint "Recuperar um único pagamento de contas" na documentação.

Segurança e boas práticas

Recomendamos:

• validar o header asaas-access-token;
• responder rapidamente com HTTP 2xx;
• implementar idempotência utilizando o identificador do evento;
• processar eventos de forma assíncrona;
• monitorar os Logs de Webhooks;
• preparar a aplicação para novos atributos adicionados futuramente.

Erros comuns

Evento duplicado

Como a entrega é do tipo at least once, um mesmo evento pode ser recebido mais de uma vez.

Utilize o campo id do evento para evitar processamento duplicado.

HTTP diferente de 2xx

Respostas diferentes da família 2xx podem provocar novas tentativas de entrega.

Novos atributos no payload

Sua aplicação deve ignorar campos desconhecidos para evitar falhas futuras.

Impactos operacionais

Caso sua aplicação não esteja preparada para receber Webhooks corretamente, podem ocorrer:

• novas tentativas de entrega;
• interrupção da fila de sincronização;
• atraso na conciliação financeira;
• inconsistências entre sistemas;
• perda permanente de eventos após 14 dias.

🚧

Atenção

• Com a entrada de novos produtos e funções dentro do Asaas, é possível que novos atributos sejam incluídos no Webhook. É muito importante que seu código esteja preparado para não gerar exceções caso o Asaas devolva novos atributos não tratados pela sua aplicação, pois isso poderá causar interrupção na fila de sincronização.
• Enviaremos um e-mail e avisaremos em nosso Discord quando novos campos forem incluídos no Webhook. O disparo será feito para o e-mail de notificação definido nas configurações do Webhook.