Webhooks do Banco do Brasil e a confirmação automática de pagamento
Esta fonte trata da integração do Banco do Brasil por API. Boleto por remessa (arquivo CNAB), configurado na forma de pagamento do ERP, é outro caminho e não usa webhook.
ONDE FICA
A tela de diagnóstico é a de webhooks da integração.
Na configuração da integração existe também o botão "Obter Webhook", que abre o modal "Webhooks da integração". Ele lista os webhooks da integração e, quando não há nenhum, mostra "Nenhum webhook foi encontrado." com o botão "Adicionar Webhooks" — esse botão cria os webhooks sem pedir URL.
O QUE A TELA DE WEBHOOKS MOSTRA
1. "URL esperada para receber notificações", gerada pelo sistema, com botão de copiar.
2. "Webhooks Cadastrados no Sistema". Vazio: "Nenhum webhook cadastrado localmente". A única ação da linha é excluir, e a confirmação avisa que isso também remove a configuração no Banco do Brasil.
3. "Webhooks Cadastrados no Banco do Brasil". Cada URL aparece marcada como "Correto" (idêntica à esperada) ou "URL diferente"; o status é Ativo ou Inativo; pela própria linha dá para ativar/desativar e excluir no banco. Vazio: "Nenhum webhook encontrado no Banco do Brasil".
4. "Últimas notificações" — as últimas recebidas para essa integração. Vazio: "Nenhuma notificação recebida ainda".
Comparar a ponta 3 com a ponta 1 é o primeiro lugar para olhar quando o pagamento não baixa.
HTTPS E REGISTRO
Quando a URL esperada não começa com https, a tela avisa em destaque que o Banco do Brasil requer URL HTTPS e acessível publicamente na internet. No modal de registro a URL já vem preenchida com a esperada; o botão Registrar fica bloqueado enquanto a URL estiver vazia, e uma URL sem https só gera aviso ("A URL deve começar com https://"), não bloqueia.
DETALHES E REPROCESSAR (só nesta tela)
"Ver detalhes" abre "Detalhes da Notificação": evento, data, mensagem de erro e as abas "Payload Recebido" e "Resposta do Processamento" (sem resposta gravada aparece "Nenhuma resposta registrada").
O reprocessar existe por um motivo: a notificação chegou, mas o processamento falhou. Reprocessar tenta de novo a partir do que já foi recebido, e a confirmação avisa que isso pode gerar duplicidade se o pagamento já foi processado.
Atenção ao vocabulário: nesta tela o status da notificação aparece em inglês, sem tradução — são os mesmos quatro estados que o Histórico mostra em português como Pendente, Processado, Falhou e Reprocessado.
HISTÓRICO DO WEBHOOK
Tela separada, por webhook, com filtros de data e mais dois filtros:
Tipo de Evento — Cobrança Paga, PIX Recebido, Cobrança Criada, Cobrança Vencida, Cobrança Cancelada.
Status de Processamento — Pendente, Processado, Falhou, Reprocessado.
Essas são as opções do filtro, não a lista de tudo que o banco pode mandar: a coluna de evento mostra o valor recebido como veio.
No topo aparecem o status do webhook (Ativo, Inativo ou Erro), a contagem de erros e a última recepção. Abrir uma linha mostra data, evento, status, IP, user agent, mensagem de erro, headers e payload. Nesta tela não há botão de reprocessar.
QUANDO NÃO BAIXA
"Nenhuma notificação recebida ainda" com boletos já pagos aponta, nessa ordem: nenhum webhook registrado no banco (registre pela tela), URL marcada como "URL diferente", webhook Inativo no banco (ative pela própria tela).
Se chegou notificação, olhe o status e a mensagem de erro antes de reprocessar.
Confira também o campo obrigatório "Email para alertas de pagamento" na configuração da integração: é por ele que chega o aviso quando ocorre algum problema na confirmação automática dos pagamentos recebidos (PIX, boleto, etc.).