Webhook do Boleto Híbrido
Notificamos os nossos clientes acerca de todas as ocorrências relacionadas aos boletos híbridos gerados pelo BS2.
Quando um boleto híbrido for, por exemplo, registrado, liquidado, cancelado ou tiver quaisquer outras ocorrências, utilizamos o Webhook para enviar tais notificações.
Cadastro de rota
Adição de uma nova configuração de webhook:
Solicitamos os campos:
| Campo | Descrição | Formato | Obrigatório |
|---|---|---|---|
| url | Endereço em que serão recebidas as notificações pelos clientes. | String | Sim |
| quantidadeRetentativas | Número de tentativas em que o evento será enviado devido a inconsistências | Interger | Sim |
| tipoEvento | O nome do evento enviado | String | Sim |
| intervaloEntreRetentativas | Intervalo de tempo em que a retentativa será executada | String | Sim |
| usuarioCriacao | Objeto contendo os dados do usuário | Objeto | Sim |
| nome | Nome do usuário | String | Sim |
| E-mail de cadastro do cliente | String | Sim | |
| identificador | Identificador do usuário | String | Sim |
| autenticacao | Objeto contendo os dados da autenticação | Objeto | Sim |
| valor | Valor da chave de autenticação | String | Sim |
| tipo | Tipo de autenticação - Ex: Token | String | Sim |
Exemplo de resposta:
| Campo | Descrição | Formato |
|---|---|---|
| Status Code | Solicitação de criação efetuada | 201 Created |
Cadastro de webhook por evento
Atualizar configuração de webhook cadastrado
Exemplo de requisição:
| Campo | Descrição | Formato | Obrigatório |
|---|---|---|---|
| configuracaoId | Identificador da configuração de webhook para atualização | String | Sim |
| url | Endereço em que serão recebidas as notificações pelos clientes | String | Sim |
| quantidadeRetentativas | Número de tentativas em que o evento será enviado devido inconsistências | String | Sim |
| intervaloEntreRetentativas | Intervalo de tempo em que a retentativa será executada | String | Sim |
| usuarioAlteracao | Objeto contendo os dados do usuário | Objeto | Sim |
| nome | Nome do usuário | String | Sim |
| E-mail de cadastro do cliente | String | ||
| identificador | Identificador do usuário | String | Sim |
| autenticacao | Objeto contendo os dados da autenticação | Objeto | Sim |
| valor | Valor da chave de autenticação | String | Sim |
| tipo | Tipo de autenticação, que pode ser: None, Basic ou Bearer | String | Sim |
Exemplo de resposta:
| Campo | Descrição | Formato |
|---|---|---|
| Status Code | Solicitação de criação efetuada | 200 Success |
Remover configuração de webhook cadastrado
Exemplo de requisição:
| Campo | Descrição | Formato | Obrigatório |
|---|---|---|---|
| configuracaoId | Identificador da configuração de webhook para atualização (Informado no QueryParams) | String | Sim |
| usuarioRemocao | Objeto contendo os dados do usuário responsável pela remoção | Objeto | Sim |
| nome | Nome do usuário | String | Sim |
| E-mail de cadastro do cliente | String | Sim | |
| identificador | Identificador do usuário | String | Sim |
Exemplo de resposta:
| Campo | Descrição | Formato |
|---|---|---|
| Status Code | Solicitação de criação efetuada | 204 No Content |
Criar certificado de configuração de webhook
Após cadastrar o webhook, é preciso registrar o certificado do DNS da rota parametrizada, na funcionalidade.
| Campo | Descrição | Formato | Obrigatório |
|---|---|---|---|
| certificado | Enviar o certificado X.509 codificado em base64 da rota do seu webhook (Arquivo *.cer) | String | Sim |
Exemplo de resposta:
| Campo | Descrição | Formato |
|---|---|---|
| Status Code | Solicitação de criação efetuada | 201 Created |
Adição de certificado para o webhook
Eventos notificados
| Campo | Descrição |
|---|---|
| BoletoHibridoErroValidacao | Notificação de inconsistência de Chaves Pix (DICT) |
| BoletoHibridoEmitido | Notificação do processo de emissão do boleto híbrido |
| BoletoHibridoRegistrado | Notificação de finalização de registro do boleto híbrido (Nuclea + Pix) |
| BoletoHibridoFalhaCancelamento | Notificação de inconsistência no processo de baixa de um boleto híbrido |
| BoletoHibridoCancelado | Notificação de baixa executada com sucesso (solicitações de baixa, liquidações e vencimentos) |
| BoletoHibridoLiquidado | Notificação de pagamento de um boleto híbrido |
| BoletoHibridoFalhaLiquidacao | Notificação de inconsistência no processo de liquidação |
BoletoHibridoErroValidacao
| Campo | Descrição | Formato |
|---|---|---|
| Codigo | Código do erro de validação. | String |
| Descricao | Descrição resumida do erro identificado. | String |
| Evento | Nome do evento que originou a notificação. | String |
| BoletoHibridoId | Identificador único do boleto híbrido. | Guid |
Exemplo de BoletoHibridoErroValidacao:
{
"codigo": ,
"descricao": "",
"evento": "boletohibrido.erro.validacao",
"boletoHibridoId": "2b7f8a60-16e3-4111-a310-53494b4da405"
}BoletoHibridoEmitido
| Campo | Descrição | Formato |
|---|---|---|
| QrCode | Conteúdo do QR Code Pix do boleto. | String |
| Valor | Valor original do boleto. | Decimal |
| LinhaDigitavel | Linha digitável para pagamento. | String |
| CodigoBarras | Código de barras do boleto. | String |
| DataVencimento | Data de vencimento do boleto. | DateTime |
| Detalhes | Informações complementares do evento. | String |
| Evento | Nome do evento que originou a notificação. | String |
| BoletoHibridoId | Identificador único do boleto híbrido. | Guid |
Exemplo de BoletoHibridoEmitido:
{
"qrCode": "00020126960014BR.GOV.BCB.PIX2574api-pix-h.bancobs2.com.br/spi/v2/cobv/f2f5a7d4-09dd-49d5-98aa-9d90bf0697c35204000053039865406811.005802BR5917Exemplo BS26014Belo Horizonte61083014000362070503***63043F94",
"valor": 811,
"linhaDigitavel": "21890010079057683700000120646088315880000081100",
"codigoBarras": "21893158800000811000010090576837000012064608",
"dataVencimento": "2026-10-03T11:15:31.1531",
"detalhes": "Cobrança em processo de registro.",
"evento": "boletohibrido.emitido",
"boletoHibridoId": "2b7f8a60-16e3-4111-a310-53494b4da405"
}BoletoHibridoRegistrado
| Campo | Descrição | Formato |
|---|---|---|
| QrCode | Conteúdo do QR Code Pix do boleto. | String |
| LinhaDigitavel | Linha digitável para pagamento. | String |
| CodigoBarras | Código de barras do boleto. | String |
| Detalhes | Informações complementares do evento. | String |
| Evento | Nome do evento que originou a notificação. | String |
| BoletoHibridoId | Identificador único do boleto híbrido. | Guid |
Exemplo de BoletoHibridoRegistrado:
{
"qrCode": "00020126960014BR.GOV.BCB.PIX2574api-pix-h.bancobs2.com.br/spi/v2/cobv/f2f5a7d4-09dd-49d5-98aa-9d90bf0697c35204000053039865406811.005802BR5917Exemplo BS26014Belo Horizonte61083014000362070503***63043F94",
"linhaDigitavel": "21890010079057683700000120646088315880000081100",
"codigoBarras": "21893158800000811000010090576837000012064608",
"detalhes": "Boleto híbrido registrado com sucesso.",
"evento": "boletohibrido.registrado",
"boletoHibridoId": "2b7f8a60-16e3-4111-a310-53494b4da405"
}BoletoHibridoFalhaCancelamento
| Campo | Descrição | Formato |
|---|---|---|
| QrCode | Conteúdo do QR Code Pix do boleto. | String |
| LinhaDigitavel | Linha digitável para pagamento. | String |
| CodigoBarras | Código de barras do boleto. | String |
| Detalhes | Motivo da falha no cancelamento. | String |
| Evento | Nome do evento que originou a notificação. | String |
| BoletoHibridoId | Identificador único do boleto híbrido. | Guid |
Exemplo de BoletoHibridoFalhaCancelamento:
{
"qrCode": "00020126960014BR.GOV.BCB.PIX2574api-pix-h.bancobs2.com.br/spi/v2/cobv/f2f5a7d4-09dd-49d5-98aa-9d90bf0697c35204000053039865406811.005802BR5917Exemplo BS26014Belo Horizonte61083014000362070503***63043F94",
"linhaDigitavel": "21890010079057683700000120646088315880000081100",
"codigoBarras": "21893158800000811000010090576837000012064608",
"detalhes": "Falha no cancelamento: Boleto.Cobranca",
"evento": "boletohibrido.falha.cancelamento",
"boletoHibridoId": "2b7f8a60-16e3-4111-a310-53494b4da405"
}BoletoHibridoCancelado
| Campo | Descrição | Formato |
|---|---|---|
| QrCode | Conteúdo do QR Code Pix do boleto. | String |
| LinhaDigitavel | Linha digitável para pagamento. | String |
| CodigoBarras | Código de barras do boleto. | String |
| Detalhes | Informações complementares do evento. | String |
| Evento | Nome do evento que originou a notificação. | String |
| BoletoHibridoId | Identificador único do boleto híbrido. | Guid |
Exemplo de BoletoHibridoCancelado:
{
"qrCode": "00020126960014BR.GOV.BCB.PIX2574api-pix-h.bancobs2.com.br/spi/v2/cobv/f2f5a7d4-09dd-49d5-98aa-9d90bf0697c35204000053039865406811.005802BR5917Exemplo BS26014Belo Horizonte61083014000362070503***63043F94",
"linhaDigitavel": "21890010079057683700000120646088315880000081100",
"codigoBarras": "21893158800000811000010090576837000012064608",
"detalhes": "Falha no processo de Registro do boleto híbrido.",
"evento": "boletohibrido.cancelado",
"boletoHibridoId": "2b7f8a60-16e3-4111-a310-53494b4da405"
}BoletoHibridoLiquidado
| Campo | Descrição | Formato |
|---|---|---|
| QrCode | Conteúdo do QR Code Pix do boleto. | String |
| LinhaDigitavel | Linha digitável para pagamento. | String |
| CodigoBarras | Código de barras do boleto. | String |
| Detalhes | Informações complementares do evento. | String |
| DataPagamento | Data e hora da liquidação. | DateTime |
| ValorPago | Valor efetivamente pago. | Decimal |
| DadosPagadorEfetivo | Dados da conta que realizou o pagamento. | Object |
| Evento | Nome do evento que originou a notificação. | String |
| BoletoHibridoId | Identificador único do boleto híbrido. | Guid |
Estrutura de DadosPagadorEfetivo:
| Campo | Descrição | Formato |
|---|---|---|
| Nome | Nome do pagador efetivo. | String |
| Documento | CPF ou CNPJ do pagador efetivo. | String |
| TipoDocumento | Tipo do documento informado. | Byte |
| BancoIspb | ISPB da instituição do pagador. | String |
| AgenciaConta | Agência vinculada à conta pagadora. | String |
| NumeroConta | Número da conta pagadora. | String |
| TipoConta | Tipo da conta utilizada no pagamento. | Byte |
Exemplo de BoletoHibridoLiquidado:
{
"qrCode": "00020126960014BR.GOV.BCB.PIX2574api-pix-h.bancobs2.com.br/spi/v2/cobv/f2929a68-57ac-4b93-a15f-205fb75ed42c5204000053039865406776.005802BR5917Exemplo BS26014Belo Horizonte61083014000362070503***63042E57",
"linhaDigitavel": "21890010079057683700000118756287615790000077600",
"codigoBarras": "21896157900000776000010090576837000011875628",
"detalhes": "Boleto Liquidado via código de barras.",
"dataPagamento": "2026-09-04T10:17:23.6320905",
"valorPago": 776,
"dadosPagadorEfetivo": {
"nome": "PAGADOR EXEMPLO BS2",
"documento": "12345678000101",
"tipoDocumento": 2,
"bancoIspb": "71027866",
"agenciaConta": "001",
"numeroConta": "99999999",
"tipoConta": 1 },
"evento": "boletohibrido.liquidado",
"boletoHibridoId": "9b8127d3-1cfe-4945-8010-20c9b27946da"
}BoletoHibridoFalhaLiquidacao
| Campo | Descrição | Formato |
|---|---|---|
| QrCode | Conteúdo do QR Code Pix do boleto. | String |
| LinhaDigitavel | Linha digitável para pagamento. | String |
| CodigoBarras | Código de barras do boleto. | String |
| Detalhes | Motivo da falha na liquidação. | String |
| Evento | Nome do evento que originou a notificação. | String |
| BoletoHibridoId | Identificador único do boleto híbrido. | Guid |
Exemplo de BoletoHibridoFalhaLiquidacao:
{
"qrCode": "00020126960014BR.GOV.BCB.PIX2574api-pix-h.bancobs2.com.br/spi/v2/cobv/f2f5a7d4-09dd-49d5-98aa-9d90bf0697c35204000053039865406811.005802BR5917Exemplo BS26014Belo Horizonte61083014000362070503***63043F94",
"linhaDigitavel": "21890010079057683700000120646088315880000081100",
"codigoBarras": "21893158800000811000010090576837000012064608",
"detalhes": "Falha no pagamento do boleto híbrido via QrCode.",
"evento": "boletohibrido.falha.liquidacao",
"boletoHibridoId": "2b7f8a60-16e3-4111-a310-53494b4da405"
}Updated 11 days ago
Did this page help you?