Webhook do PIX

Através do webhook, notificamos nossos clientes sobre os pagamentos e recebimentos PIX.

Criando uma rota

É necessário que o cliente cadastre uma rota acessível na internet para receber as notificações do webhook.

Podem ser cadastradas rotas para cada tipo de evento transacional, conforme listado abaixo, ou uma rota para receber todos os eventos.

Atualmente notificamos os seguintes eventos:

Tipo	Descrição	Callback
Pagamento	Ocorre toda vez que um pagamento é realizado com sucesso	Pagamento - Consultar - PagamentoId
Recebimento	Ocorre toda vez que uma transação PIX é recebida em conta com sucesso.	Recebimento - Consultar por EndToEndId
ValidacaoChaves	Ocorre como resposta da API de validação de chaves, informando se a chave é válida ou não	-

Através do contrato abaixo será possível cadastrar o webhook desejado.

Solicitamos os campos:

Campo	Descrição	Formato	Obrigatório
url	URL do cliente que receberá o evento quando disparado de acordo com a regra de negócio do evento	string	Sim
eventos	Tipo de envento que deseja receber, com as opções "Pagamento" , "Recebimento" e "ValidacaoChaves"	array	Sim
autorizacao	Mecanismo de segurança que o BS2 utilizará para enviar o webhook. Enum: "none" "basic" "bearer"	object	Sim

Como resposta, enviamos status de sucesso (família HTTP 200).

Webhook - Criar/Atualizar

⚠️
Importante:

Realizamos algumas tentativas de reenvio do webhook, e após quantidade de tentativas, os reenvios cessam;

Se a URL cadastrada demorar mais de 1000ms para receber a notificação, o envio do webhook é cancelado;

Ressaltamos que: falhas podem ocorrer em ambos os lados (BS2 ou cliente), por isso é importante que seja configurado um mecanismo de callback nas apis de consulta de transação.

Registrando o certificado DNS

Após cadastrar o webhook é preciso registrar o certificado do DNS da rota parametrizada. E essa ação deve ser realizada através do método Webhook - Certificado - Inclusão/Atualização.

Solicitamos o campo:

Campo	Descrição	Formato	Obrigatório
certificado	Enviar o certificado X.509 codificado em base64 da rota do seu webhook (Arquivo *.cer)	string	Sim

Como resposta, enviamos status de sucesso (família HTTP 200).

Mais detalhes de como configurar o DNS no link Como registrar DNS.

Obtendo configurações do webhook

Retornamos as configurações de todos os webhooks cadastrados em todas as contas do cliente.

Resposta:

Tipo	Descrição	Formato	Nullable
id	Identificador único do webhook	string	Sim
evento	Tipo de envento que deseja receber, com as opções "Pagamento" , "Recebimento" e ValidacaoChaves	string	Não
contaNumero	Número da conta vinculada webhook	integer	Não
somenteComTxId	Dado obsoleto	-	-
url	URL cadastrada para receber o evento	string	Sim
autorizacao	Mecanismo de segurança que o BS2 utilizará para enviar o webhook. Enum: "none" "basic" "bearer"	object	Sim

Webhook - Obter

Excluindo o Webhook

Essa funcionalidade permite excluir um webhook configurado.

Solicitamos os campos:

Tipo	Descrição	Formato	Obrigatório
Id	Identificador do webhook configurado	string	Sim

Como resposta, enviamos status de sucesso (família HTTP 200).

Obtenha o Id pelo método Webhook - Obter