Visão Geral Os webhooks de PIX Cash In notificam seu sistema em tempo real sobre mudanças de status nas cobranças PIX, garantindo que você possa processar pedidos e atualizar sua aplicação imediatamente após os pagamentos.
Todos os webhooks são enviados via POST com payload JSON e assinatura de segurança.
Status dos Webhooks PAID Transação PIX foi paga com sucesso pelo cliente. Valores creditados na conta.
ERROR Transação PIX falhou durante o processamento. Pode ocorrer por diversos motivos técnicos.
Configuração Configure a URL do webhook PIX através do endpoint de configuração de conta:
curl --request POST \ --url https://api-gateway.firebanking.com.br/v1/account/webhook \ --header 'x-api-key: sua_chave_api' \ --header 'Content-Type: application/json' \ --data '{ "pixWebhookUrl": "https://meusite.com.br/webhooks/pix" }' Payload dos Webhooks PIX Recebido (Status: PAID) { "transactionId" : "03cadd36-fddd-4091-9ffe-67b0483cbcf5" , "businessTransactionId" : "pedido-12345" , "status" : "PAID" , "value" : 15000 , "movementType" : "CREDIT" , "endToEndId" : "E00000000202401151045300123456789" , "pixKey" : "[email protected] " , "createdDate" : "2024-01-15T10:30:00.123Z" , "ReceiverBankAccount" : "567890" , "ReceiverToBankAccountDigit" : "1" , "ReceiverBankBranch" : "0001" , "ReceiverBankCode" : "077" , "ReceiverDocumentNumber" : "45438750000188" , "ReceiverBankName" : "BANCO INTER S.A." , "ReceiverBankISPB" : "00416968" , "ReceiverName" : "MINHA EMPRESA LTDA" , "PayerBankAccount" : "123456" , "PayerBankAccountDigit" : "7" , "PayerBankBranch" : "0001" , "PayerBankCode" : "001" , "PayerDocumentNumber" : "12345678901" , "PayerBankName" : "BANCO DO BRASIL S.A." , "PayerBankISPB" : "00000000" , "PayerName" : "JOAO COSTA SILVA" , "VoucherUrl" : "https://voucher.firebanking.com/pix/03cadd36-fddd-4091-9ffe-67b0483cbcf5.pdf" } { "transactionId" : "error-1234-5678-9abc-def012345678" , "businessTransactionId" : "pedido-erro-12345" , "status" : "ERROR" , "value" : 15000 , "movementType" : null , "endToEndId" : null , "pixKey" : "[email protected] " , "createdDate" : "2024-01-15T14:30:45.123Z" , "ReceiverBankAccount" : null , "ReceiverToBankAccountDigit" : null , "ReceiverBankBranch" : null , "ReceiverBankCode" : null , "ReceiverDocumentNumber" : null , "ReceiverBankName" : null , "ReceiverBankISPB" : null , "ReceiverName" : null , "PayerBankAccount" : null , "PayerBankAccountDigit" : null , "PayerBankBranch" : null , "PayerBankCode" : null , "PayerDocumentNumber" : null , "PayerBankName" : null , "PayerBankISPB" : null , "PayerName" : null , "VoucherUrl" : null } Campos da Transação Estrutura Principal ID único da transação (ObjectId)
ID do business que recebeu o PIX
Dados do pagador (cliente externo)
Data de criação da transação (ISO 8601)
Data da última atualização (ISO 8601)
Campo Operation Tipo da operação: PAYMENT ou REFUND
Direção: sempre IN (recebimento)
Tipo de movimento: CREDIT (entrada) ou DEBIT (saída)
Valor original em centavos (R$ 150,00 = 15000)
Valor efetivado em centavos
Provedor utilizado: CELCOIN, WOOVI, etc.
ID da transação no provedor
ID externo fornecido pelo cliente
operation.additionalInfo.endToEndId
ID end-to-end do PIX (BACEN)
Implementação do Webhook Endpoint Receptor Node.js/Express
Python/Flask
PHP
const express = require ( 'express' ); const crypto = require ( 'crypto' ); const app = express (); app . use ( express . raw ({ type: 'application/json' })); app . post ( '/webhooks/pix' , ( req , res ) => { const signature = req . headers [ 'x-firebanking-signature' ]; const payload = req . body ; // Verificar assinatura if ( ! verifySignature ( payload , signature )) { return res . status ( 401 ). send ( 'Unauthorized' ); } const webhook = JSON . parse ( payload ); switch ( webhook . operation . status ) { case 'PAID' : handlePaymentReceived ( webhook ); break ; case 'ERROR' : handleTransactionError ( webhook ); break ; } res . status ( 200 ). send ( 'OK' ); }); function verifySignature ( payload , signature ) { const secret = process . env . FIREBANKING_WEBHOOK_SECRET ; const hash = crypto . createHmac ( 'sha256' , secret ) . update ( payload ) . digest ( 'hex' ); return signature === `sha256= ${ hash } ` ; } function handlePaymentReceived ( transaction ) { console . log ( `PIX recebido: R$ ${ transaction . operation . value / 100 } ` ); console . log ( `End-to-end ID: ${ transaction . operation . additionalInfo . endToEndId } ` ); console . log ( `Cliente: ${ transaction . payer . fullName } ` ); // Processar pedido, enviar produto, etc. updateOrderStatus ( transaction . operation . externalID , 'paid' ); sendConfirmationEmail ( transaction . payer . fullName ); } app . listen ( 3000 );
Segurança Verificação de Assinatura Todos os webhooks incluem uma assinatura HMAC-SHA256 no header X-Firebanking-Signature:
X-Firebanking-Signature: sha256=a1b2c3d4e5f6... Testando Webhooks Ambiente de Desenvolvimento Use ferramentas como ngrok para testar localmente:
# Expor localhost:3000 ngrok http 3000 # Configurar webhook PIX curl -X POST https://api-gateway.firebanking.com.br/v1/account/webhook \ -H 'x-api-key: sua_chave_api' \ -H 'Content-Type: application/json' \ -d '{"pixWebhookUrl": "https://abc123.ngrok.io/webhook"}' Monitoramento Dashboard de Webhooks Acompanhe a saúde dos seus webhooks:
Taxa de sucesso
Tentativas de retry
Webhooks falhados
Tempo de resposta
Boas Práticas
Resposta rápida : Retorne 200 imediatamenteProcessamento assíncrono : Use filas para tarefas demoradasCache de duplicatas : Evite reprocessamentoTimeout adequado : Configure timeout do servidor
Confiabilidade
Valideção rigorosa : Sempre verifique assinaturaIdempotência : Trate webhooks duplicadosRetry manual : Tenha processo para webhooks falhadosMonitoring : Monitore taxas de sucesso
Segurança
HTTPS obrigatório : Nunca use HTTPValidação de origem : Confirme que vem da FireBankingLog de segurança : Registre tentativas de webhookSecret seguro : Mantenha webhook secret em variáveis de ambiente
Próximos Passos 
