Como integrar o Asaas ao GoHighLevel

O que você precisa antes de começar

• Conta no Asaas com acesso a Integrações (chave de API e webhooks)
• Conta de Sandbox no Asaas para testar antes de ir para produção
• Workflow Premium Features ligado na agência do GoHighLevel (Inbound Webhook e Custom Webhook são recursos premium)
• Uma camada intermediária, como n8n, Make ou um servidor próprio, para consultar o cliente na API do Asaas
• Acesso de administrador à subconta do GoHighLevel

Passo a passo

1. 1

   Ative os recursos premium de workflow

   Na visão de agência do GoHighLevel, vá em Configurações → Empresa → Workflow - Premium Features e ligue a opção. Sem isso o gatilho Inbound Webhook e a ação Custom Webhook não ficam disponíveis.

   Ligar o recurso na agência não configura o rebilling de cada subconta. Se você repassa custos ao cliente, ajuste isso em cada subconta, na área de gerenciamento do cliente.

2. 2

   Crie o workflow com o gatilho Inbound Webhook

   Na subconta, crie um workflow e escolha o gatilho Inbound Webhook. O GoHighLevel gera uma URL exclusiva para esse gatilho, que aceita requisições POST, GET ou PUT com corpo em JSON. Copie essa URL.

3. 3

   Monte a etapa intermediária

   No n8n (ou ferramenta equivalente), crie um fluxo que recebe o webhook do Asaas, lê o campo payment.customer e consulta GET /v3/customers/{id} na API do Asaas, enviando a chave no cabeçalho access_token. A resposta traz nome, e-mail, telefone e celular do cliente. Depois, envie para a URL do GoHighLevel um JSON com esses dados mais o evento, o valor, o vencimento e o ID da cobrança.

   O GoHighLevel exige e-mail ou telefone no corpo para encontrar ou criar o contato. Mandar o aviso do Asaas direto para o GoHighLevel não funciona para isso, porque ele traz apenas o ID do cliente.

4. 4

   Cadastre o webhook no Asaas

   No Asaas, abra Menu do usuário → Integrações → Webhooks → Criar Webhook. Informe a URL pública da sua etapa intermediária, um e-mail para alertas e um Auth Token. Selecione só os eventos que você vai tratar, como PAYMENT_RECEIVED, PAYMENT_CONFIRMED, PAYMENT_OVERDUE e PAYMENT_REFUNDED.

   O Asaas envia o Auth Token no cabeçalho asaas-access-token. Valide esse cabeçalho na etapa intermediária antes de processar qualquer evento — é o que impede alguém de forjar um pagamento confirmado.

5. 5

   Teste e mapeie os campos no GoHighLevel

   Gere uma cobrança no Sandbox do Asaas e pague-a para disparar o evento. No gatilho do GoHighLevel, clique em Test Trigger, escolha a requisição recebida e salve como amostra. Em seguida, mapeie e-mail, telefone e nome na ação de criar ou atualizar contato.

   As chaves do JSON não podem ter espaços: use snake_case ou camelCase. Sandbox e produção têm contas, chaves e URLs separadas (api-sandbox.asaas.com e api.asaas.com) — trocar só uma delas é a causa clássica de erro 401.

6. 6

   Ramifique o workflow por evento

   Use uma condição sobre o campo do evento. Pagamento recebido: mova a oportunidade para ganha, aplique uma etiqueta e inicie o onboarding. Cobrança vencida: inicie a sequência de recuperação por WhatsApp, SMS ou e-mail com o link da fatura. Estorno: avise a equipe e retire o acesso, se for o caso.

7. 7

   Opcional: crie cobranças no Asaas a partir do GoHighLevel

   A ação Custom Webhook do workflow permite chamar a API do Asaas com cabeçalhos personalizados — por exemplo, enviar access_token e criar uma cobrança quando a oportunidade chega a uma etapa. A cobrança precisa de um cliente já cadastrado no Asaas, então o fluxo costuma criar ou localizar o cliente antes.

   A chave de API do Asaas dá acesso à conta de cobrança. Prefira deixar essa chamada na etapa intermediária, onde a chave fica guardada como credencial, em vez de espalhá-la por vários workflows.

Limitações que valem saber antes

• Não há integração nativa documentada: a central de ajuda e o marketplace da HighLevel não trazem o Asaas como provedor de pagamento, então checkout, faturas e produtos do GoHighLevel não cobram pelo Asaas.
• O webhook de cobrança do Asaas traz só o ID do cliente. Sem uma etapa que consulte a API do Asaas, o GoHighLevel não consegue identificar o contato.
• Inbound Webhook e Custom Webhook são execuções premium: cada subconta tem 100 execuções gratuitas vitalícias, e depois a HighLevel cobra US$ 0,01 por execução. Os planos Workflow Pro incluem uma franquia mensal e cobram o excedente com desconto.
• O Asaas entrega eventos no modelo "pelo menos uma vez": o mesmo evento pode chegar repetido. Guarde o ID do evento e descarte duplicados, ou o cliente recebe a mensagem de boas-vindas duas vezes.
• Após 15 falhas seguidas a fila de webhooks do Asaas é interrompida, e eventos parados por mais de 14 dias são apagados. Se a etapa intermediária sair do ar, os avisos param de chegar ao CRM.
• No cartão de crédito, o Asaas emite PAYMENT_CONFIRMED no pagamento e PAYMENT_RECEIVED só quando o dinheiro fica disponível, cerca de 32 dias depois. Disparar o onboarding apenas em PAYMENT_RECEIVED atrasa a entrega de quem pagou no cartão.

Perguntas frequentes

Qual evento usar para liberar o acesso: PAYMENT_CONFIRMED ou PAYMENT_RECEIVED?

Segundo a documentação do Asaas, PAYMENT_CONFIRMED indica que o pagamento foi feito mas o saldo ainda não está disponível, e PAYMENT_RECEIVED indica que o valor já está na conta. Pix e boleto costumam ir direto para PAYMENT_RECEIVED; cartão passa antes por PAYMENT_CONFIRMED. Para não deixar quem pagou no cartão esperando, trate os dois eventos e evite executar a entrega duas vezes.

Dá para apontar o webhook do Asaas direto para o GoHighLevel, sem n8n?

O GoHighLevel recebe o aviso, mas não consegue achar o contato: o Inbound Webhook exige e-mail ou telefone, e o evento de cobrança do Asaas traz apenas o ID do cliente. Além disso, a documentação do gatilho não descreve validação de cabeçalhos, então o asaas-access-token não seria conferido. Por isso a etapa intermediária é o caminho recomendado.

O Asaas pode ser o checkout dos funis do GoHighLevel?

Não de forma nativa: a HighLevel não documenta o Asaas como provedor de pagamento. Para cobrar dentro dos funis, use um provedor nativo como Mercado Pago ou Stripe; o Asaas funciona como sistema de cobrança paralelo, que informa o CRM por webhook.

Como testar sem cobrar ninguém de verdade?

Crie uma conta no Sandbox do Asaas, que é independente da conta de produção e tem chaves próprias. Cadastre ali um webhook apontando para a mesma etapa intermediária e gere cobranças de teste até o workflow do GoHighLevel se comportar como esperado.