Introdução

Um webhook é uma notificação automática: sempre que ocorre um evento de seu interesse (por exemplo, um crédito Pix recebido na conta de um cliente, ou o resultado de um cadastro de conta digital), o Pinbank envia uma requisição HTTP POST para uma URL que você configura, contendo os dados do evento.

Não é necessário fazer polling em nenhuma API — a entrega é push, iniciada pela Pinbank.

Pré-requisito: o evento que você deseja receber precisa estar habilitado para os seus produtos contratados com o Pinbank. Ao contratar novos produtos cujos eventos ainda não estejam disponíveis, entre em contato com o suporte Pinbank para confirmar a habilitação antes de validar a integração.

💡

Caso necessário realizar liberação/filtro de IP do lado do consumidor o nosso IP de saída é 20.106.240.61

Como funciona, em 3 passos

Você registra seu canal — informa pra qual URL enviar, quais eventos você quer receber, e regras de retentativa. Veja Registrando um canal.

A Pinbank entrega o evento — sempre que o evento ocorre, um POST chega no seu endpoint com o payload e headers de autenticidade. Veja Estrutura da entrega.

Você valida e processa — confere a assinatura Ed25519, responde rápido, processa depois. Veja Autenticidade e o Checklist de integração.

Como integrar

Quero configurar o meu webhook → Configurando o webhook

Quero validar a autenticidade das entregas → Autenticidade — assinatura Ed25519

Quero saber o payload de um evento específico → Eventos disponíveis

Vou implementar agora → Checklist de integração

PIX

Domínio	Evento	Descrição
Pix	`Pix.CreditoRecebido`	Um Pix foi recebido e confirmado na conta digital de um cliente.
Pix	`Pix.TransferenciaRealizada`	Resultado do processamento de uma transferência Pix enviada por um cliente — cobre sucesso e falha.
Pix	`Pix.DevolucaoEnviada`	Confirmação do Bacen sobre uma devolução Pix enviada por um cliente (cliente = pagador da devolução).
Pix	`Pix.DevolucaoRecebida`	Devolução Pix processada e creditada na conta de um cliente (cliente = recebedor da devolução).

Conta Digital (Gestão de Contas)

Domínio	Evento	Descrição
Conta Digital	`ContaDigital.CadastroPf`	Resultado do cadastro de pessoa física/jurídica — cobre sucesso e erro.
Conta Digital	`ContaDigital.ValidacaoCliente`	Resultado da validação de disponibilidade de um dado (CPF, e-mail, celular) — dispara em toda tentativa, sucesso ou falha.

Compras (Transacional)

Domínio	Evento	Descrição
Compra	`Compra.TransacaoPendente`	Transação de cartão recém-criada, antes do resultado do adquirente.
Compra	`Compra.TransacaoRealizada`	Transação de cartão aprovada pelo adquirente.
Compra	`Compra.TransacaoNegada`	Transação de cartão negada (pelo adquirente, ou em validação prévia antes de chegar ao adquirente).
Compra	`Compra.TransacaoCancelada`	Transação de cartão cancelada.
Compra	`Compra.TransacaoDesfeita`	Transação de cartão desfeita (estorno no mesmo dia).
Compra	`Compra.TransacaoReembolsada`	Transação de cartão reembolsada.
Compra	`Compra.PixCobrancaPendente`	Transação Pix (via rede de cartão) recém-criada, antes do resultado.
Compra	`Compra.PixTransferenciaRealizada`	Transferência Pix (via rede de cartão) confirmada.
Compra	`Compra.PixTransferenciaNegada`	Transferência Pix (via rede de cartão) negada.
Compra	`Compra.PixCobrancaInvalidada`	QR Code Pix invalidado antes de ser pago — não é transferência revertida, é cobrança abandonada.

Boletos / Títulos

Domínio	Evento	Descrição
Boleto	`Boleto.Registro`	Boleto registrado com sucesso e disponível para pagamento.
Boleto	`Boleto.Liquidacao`	Boleto pago — retorno de cobrança acolhido pela Pinbank.
Boleto	`Boleto.Baixa`	Título baixado — cobre baixa a pedido do cedente, da instituição e por pagamento via Pix.

Como funciona, em 3 passos#

Como integrar#

PIX#

Conta Digital (Gestão de Contas)#

Compras (Transacional)#

Boletos / Títulos#

Como funciona, em 3 passos

Como integrar

PIX

Conta Digital (Gestão de Contas)

Compras (Transacional)

Boletos / Títulos