C6 Bank: webhooks e o pagamento que não deu baixa sozinho
O QUE É O WEBHOOK DO C6 BANK
Webhook é o aviso que o C6 Bank manda para o sistema quando alguma coisa acontece com a cobrança, por exemplo o boleto ou o Pix que o seu cliente pagou. É esse aviso que dispara a baixa automática. Sem ele, o dinheiro cai na conta do banco e o sistema continua achando que a cobrança está em aberto. Por isso, quando alguém diz "o cliente pagou e não baixou", a investigação começa aqui e não no financeiro.
ONDE FICA A TELA
Cada integração do C6 Bank tem a sua própria tela de webhooks, com a sua própria URL. A trilha no topo dela mostra C6 Bank, Integrações, Editar, Webhooks. A tela tem um botão Voltar que leva de volta à edição da integração.
Atenção ao orientar o cliente: não confirme por qual menu, aba ou botão se chega até essa tela. A tela de edição da integração é uma página só, com os blocos de informações da integração, credenciais, forma de pagamento, multa e juros, mensagens e notificações, e não tem uma aba de webhooks. Se o cliente perguntar o caminho, ofereça verificar junto com ele na conta dele em vez de descrever um caminho de memória.
Se você tem mais de uma integração cadastrada, confira que está olhando a certa: cada integração tem a sua própria tela de webhooks, e é a integração aberta que define o que você está vendo.
Existe ainda uma área de webhooks separada dentro do módulo do C6, com cadastro, edição, visualização e uma tela de histórico por webhook. Essa tela de histórico filtra por tipo de evento, situação do processamento e período, e o detalhe de cada requisição mostra IP, User Agent, identificador da transação, mensagem de erro, cabeçalhos e conteúdo recebido. Se essa área não abrir na conta, use a tela de dentro da integração: ela tem o que o diagnóstico precisa.
O QUE CADA BLOCO DA TELA MOSTRA
Informações Gerais traz o ID da integração, a situação dela e a URL esperada para receber notificações, com um botão que copia essa URL e avisa "URL copiada!". É essa URL que precisa estar cadastrada no C6.
Webhooks Cadastrados no Sistema é o que está gravado aqui no ERP: ID, URL, tipos, situação e data de criação, com o botão de excluir. Quando não há nada, a tela diz "Nenhum webhook cadastrado localmente".
Webhooks Cadastrados no C6 Bank é o que o banco tem registrado: ID, nome, URL, situação (Ativo ou Inativo) e tipo. Ao lado de cada URL o sistema mostra um selo: se a URL for igual à esperada, aparece Correto; se for diferente, aparece URL diferente. Quando não há nada registrado, a tela avisa que nenhum webhook foi encontrado no C6 Bank e oferece o link do painel do banco para conferir por lá. E se a consulta ao banco falhar, no lugar da tabela aparece um aviso amarelo com a mensagem devolvida — nesse caso o problema é a consulta ao C6, não a ausência de webhook, e vale olhar o estado da integração antes de qualquer outra coisa.
Últimas notificações é o histórico do que chegou: ID, evento, situação do processamento, mensagem de erro e data. Cada linha tem reprocessar e ver detalhes. Esse bloco mostra as notificações mais recentes daquela integração, até vinte — em conta com movimento alto, uma notificação antiga pode simplesmente não estar mais na lista.
A URL PRECISA SER HTTPS
Segundo a própria tela, o C6 Bank exige que a URL do webhook seja HTTPS e acessível publicamente na internet. Se a URL esperada não começar com https, a tela abre um aviso em amarelo dizendo que aquela URL não funcionará em produção. Na janela de registro, se você digitar um endereço que não comece com https, o campo fica marcado como inválido e o mesmo aviso aparece — mas o botão Registrar continua clicável, então não conte com o sistema para te impedir. Uma URL que o banco não alcança faz a notificação nunca chegar, e o sintoma final é exatamente o pagamento sem baixa.
REGISTRAR, ATIVAR, DESATIVAR E EXCLUIR
O botão Registrar webhook no c6 abre uma janela já com a URL esperada preenchida. Você pode alterar, e existe um botão para restaurar a URL padrão. Confirmando, se o registro for aceito o sistema avisa que o webhook foi registrado e recarrega as duas listas; se der erro, mostra a mensagem devolvida.
Na lista dos webhooks do C6 Bank, o botão de pausa desativa e o de play ativa, sempre com uma confirmação antes. Desativar é o caminho quando você quer parar de receber temporariamente sem perder o cadastro. Excluir do C6 Bank é definitivo, e a confirmação avisa que a ação não pode ser desfeita.
Atenção a uma diferença que confunde: ao excluir um webhook na lista Webhooks Cadastrados no Sistema, a confirmação diz, com todas as letras, que isso também removerá a configuração no C6 Bank. Ou seja, não é uma limpeza só do registro local.
O HISTÓRICO DE NOTIFICAÇÕES
O bloco Últimas notificações responde à pergunta mais importante do atendimento: o banco chegou a avisar? Se não existe nenhuma linha para o pagamento em questão, a hipótese mais forte é que a notificação não chegou, e a investigação volta para o cadastro do webhook. Lembrando que a lista traz só as mais recentes.
Se existe a linha, olhe a situação do processamento. As situações previstas são pendente, processado, falhou e reprocessado. Na tela de dentro da integração esses quatro valores aparecem em inglês, sem tradução; na tela de histórico do módulo aparecem em português. Falhou significa que o aviso chegou e o processamento não se completou.
Em Ver detalhes você tem o ID, a situação, o evento, a data, a mensagem de erro completa e duas abas: Payload Recebido, com o conteúdo que veio do banco, e Resposta do Processamento. Quando ainda não existe resposta registrada, a própria tela diz que reprocessar gera essa resposta. A mensagem de erro é o que resolve o chamado. Leia antes de qualquer outra ação.
REPROCESSAR, COM CUIDADO
Reprocessar manda o sistema tentar de novo a mesma notificação. Antes de executar, aparece uma confirmação avisando que isso pode gerar duplicidade se o pagamento já foi processado. O aviso é sério: reprocessar uma notificação que já deu certo é a forma mais comum de criar um segundo recebimento para a mesma cobrança.
A regra prática: só reprocesse depois de ler a mensagem de erro, entender o motivo da falha e corrigir esse motivo. Reprocessar sem corrigir a causa tende a repetir o mesmo erro. Reprocessar sem verificar se já baixou tende a duplicar.
ORDEM DE DIAGNÓSTICO QUANDO O CLIENTE PAGOU E NÃO BAIXOU
Primeiro, abra a tela de Webhooks daquela integração e veja se existe webhook na lista do C6 Bank, se ele está Ativo e se está com o selo Correto.
Segundo, olhe Últimas notificações e procure a notificação daquele pagamento. Chegou ou não chegou.
Terceiro, se chegou, veja a situação. Se estiver com falha, abra Ver detalhes e leia a mensagem de erro e o conteúdo recebido.
Quarto, só depois de entender e corrigir o erro, use reprocessar, conferindo antes se aquela cobrança já não foi baixada.
Quinto, na tela de edição da integração, confira a forma para recebimento boleto, a forma para recebimento Pix e o e-mail para alertas de pagamento.
O QUE COSTUMA DAR ERRADO
Nenhum webhook ativo no C6. A tela mostra que nenhum webhook foi encontrado, ou o que existe está Inativo. Nada chega e nada baixa. Registre pela tela e confirme que ficou Ativo.
Selo URL diferente. Existe webhook no banco, mas apontando para outro endereço. O C6 entrega a notificação em outro lugar. Registre a URL esperada e trate o cadastro antigo.
URL que não é HTTPS ou não é pública. O banco não consegue entregar. O aviso amarelo da tela é o sintoma.
A notificação chegou e falhou. O webhook está certo e o problema é no processamento. Aqui não existe causa única: a mensagem de erro em Ver detalhes é que diz o que foi. Não chute a causa para o cliente.
Reprocessar antes de ler o erro. Devolve o mesmo erro, ou pior, duplica um recebimento que já tinha sido feito.
Parou do nada de dar baixa automática. Compare os dois blocos, o do sistema e o do C6 Bank, e veja o que deixou de bater: webhook ausente, inativo, com URL diferente, ou uma mensagem de erro no lugar da tabela do banco. Não afirme o que aconteceu antes de olhar.
O E-MAIL DE ALERTA E AS FORMAS DE PAGAMENTO
Na tela de edição da integração, no bloco Notificações, existe o campo Email para alertas de pagamento, obrigatório. O texto do campo explica para que serve: receber alertas caso ocorra algum problema na confirmação automática dos pagamentos recebidos (PIX, boleto, etc.). Se o cliente recebeu esse e-mail, é o sistema dizendo que uma confirmação falhou. Vá para a tela de Webhooks e siga a ordem de diagnóstico.
No bloco Forma de pagamento da mesma tela ficam a Forma para recebimento boleto e a Forma para recebimento Pix, as duas obrigatórias, que associam uma forma de pagamento do financeiro à emissão de boletos e de Pix no C6 Bank; junto do Pix aparece também a Chave Pix, e há um campo Forma de pagamento usado quando a integração realiza pagamentos. Esses blocos só aparecem com a integração ativa ou conectada — se ela estiver desconectada, a tela mostra o fluxo de conexão no lugar. Como funciona uma forma de pagamento e como ela se liga a uma conta bancária é assunto do ERP: a regra geral de vincular uma forma de pagamento a uma integração está na fonte raiz de Integrações e na pasta de Meios de pagamento. Se a forma desejada não aparecer na busca, não afirme o motivo — verifique junto com o cliente.
O QUE NÃO PROMETEMOS
O tempo que o banco leva para enviar a notificação, quantas vezes ele tenta e em que ordem são regras do C6 Bank, não do ERP. Não trabalhe com prazo estimado no atendimento e não confirme data de liberação nem disponibilidade para o cliente.
Por fim, nunca peça nem repita token, chave, certificado ou senha por chat ou e-mail, e não cole conteúdo de notificação com dado sensível. Se o cliente enviar alguma credencial, oriente a gerar uma nova no portal do banco.