É possível utilizar Webhooks para que seu sistema seja notificado sobre alterações que ocorram na situação cadastral das contas.

Os eventos que o Asaas notifica são:

• ACCOUNT_STATUS_BANK_ACCOUNT_INFO_APPROVED - Conta bancária aprovada.
• ACCOUNT_STATUS_BANK_ACCOUNT_INFO_AWAITING_APPROVAL - Conta bancária em análise.
• ACCOUNT_STATUS_BANK_ACCOUNT_INFO_PENDING - Conta bancária voltou para pendente.
• ACCOUNT_STATUS_BANK_ACCOUNT_INFO_REJECTED - Conta bancária reprovada.
• ACCOUNT_STATUS_COMMERCIAL_INFO_APPROVED - Informações comerciais aprovadas.
• ACCOUNT_STATUS_COMMERCIAL_INFO_AWAITING_APPROVAL - Informações comerciais em análise.
• ACCOUNT_STATUS_COMMERCIAL_INFO_PENDING - Informações comerciais voltaram para pendente.
• ACCOUNT_STATUS_COMMERCIAL_INFO_REJECTED - Informações comerciais reprovadas.
• ACCOUNT_STATUS_DOCUMENT_APPROVED - Documentos aprovados.
• ACCOUNT_STATUS_DOCUMENT_AWAITING_APPROVAL - Documentos em análise.
• ACCOUNT_STATUS_DOCUMENT_PENDING - Documentos voltaram para pendente.
• ACCOUNT_STATUS_DOCUMENT_REJECTED - Documentos reprovados.
• ACCOUNT_STATUS_GENERAL_APPROVAL_APPROVED - Conta aprovada.
• ACCOUNT_STATUS_GENERAL_APPROVAL_AWAITING_APPROVAL - Conta em análise.
• ACCOUNT_STATUS_GENERAL_APPROVAL_PENDING - Conta voltou para pendente.
• ACCOUNT_STATUS_GENERAL_APPROVAL_REJECTED - Conta reprovada.

Eventos para a confirmação anual de dados comerciais:

• ACCOUNT_STATUS_COMMERCIAL_INFO_EXPIRING_SOON - Os dados comerciais estão próximos da expiração.
• ACCOUNT_STATUS_COMMERCIAL_INFO_EXPIRED - Os dados comerciais expiraram.

Quando utilizar

Os Webhooks de situação cadastral são recomendados quando sua aplicação precisa acompanhar automaticamente alterações cadastrais das contas.

Alguns exemplos:

• acompanhamento de onboarding;
• habilitação automática de funcionalidades;
• monitoramento de subcontas;
• atualização de CRMs e ERPs;
• notificações para clientes;
• controle da confirmação anual dos dados comerciais.

Comportamentos importantes

Os Webhooks do Asaas seguem o modelo de entrega at least once, ou seja, um mesmo evento poderá ser reenviado.

Por esse motivo, recomendamos implementar idempotência utilizando o campo:

id

Além disso:

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

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": "ACCOUNT_STATUS_COMMERCIAL_INFO_APPROVED",
    "dateCreated": "2024-06-12 16:45:03",
    "account": {
        "id": "47ed0d25-f9fb-4b35-b23a-d8895caf92b7",
        "ownerId": null
    },
    "accountStatus": {
        "id": "175027c1-029c-41e5-8b9a-e289b9788c33",
        "commercialInfo": "APPROVED",
        "bankAccountInfo": "APPROVED",
        "documentation": "APPROVED",
        "general": "APPROVED"
    }
}

Campos importantes

👍

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 "Consultar situação cadastral da conta" na documentação.

Segurança

Recomendamos:

• validar o header asaas-access-token;
• responder rapidamente utilizando HTTP 200;
• processar os eventos de forma assíncrona;
• implementar idempotência utilizando o identificador do evento;
• monitorar os Logs de Webhooks;
• permitir novos atributos no payload sem gerar exceções.

Erros comuns

Evento duplicado

Os Webhooks seguem o modelo de entrega at least once. O mesmo evento poderá ser reenviado.

Utilize o campo id para evitar processamentos duplicados.

HTTP diferente de 2xx

Respostas fora da família 2xx podem provocar novas tentativas de entrega e eventual interrupção da fila.

Campos desconhecidos

Novos atributos podem ser adicionados futuramente.

Sua aplicação deve ignorar campos não reconhecidos para manter compatibilidade.

Impactos operacionais

Falhas no processamento podem provocar:

• novas tentativas de entrega;
• interrupção da fila de sincronização;
• inconsistências entre sistemas;
• atraso na atualização do status cadastral;
• perda permanente dos 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.