Cadastrando notificações de Webhook

Nossa API conta com um recurso que faz o envio de Webhooks, ou seja, envia Jsons com notificações de alteração dos boletos diretamente para a sua aplicação.

Os chamados WebHooks são notificações que nós te enviaremos sempre que um boleto retornar do banco.

Então, como o tempo de processamento das remessas varia muito de banco para banco, nós implementamos este recurso para que os sistemas de nossos clientes consigam obter as informações atualizadas dos boletos assim que elas forem disponibilizadas para nós.

É um recurso muito interessante para ser utilizado juntamente com a nossa Transmissão Automática de Remessas e Retornos. Porque, tudo estando automatizado, seu sistema não precisará "desperdiçar" consultas, enviando para nossa API pedidos de consultas para boletos que ainda não estiverem sido processados pelo banco.

Com os WebHooks da Tecnospeed, nós iremos te avisar assim que o boleto for atualizado em nossa base de dados!

O envio ocorre assim que um evento cadastrado é acionado, e em caso de falha na entrega da notificação, é feito mais 3 tentativas de entrega, geralmente espaçadas em um intervalo de 15 segundos.

Esta documentação mostrará como fazer o cadastro dos Webhooks via integração HTTP (via API).

Obs.: Atualmente as notificações por WebHooks funcionam apenas em ambiente de produção no PlugBoleto.

POST

 Homologação:

 Produção:

Headers

Body

*No campo eventos deve ser passado um objeto contendo os eventos que deseja cadastrar, os seguintes eventos são aceitados pela aplicação, "registrou", "liquidou", "baixou", "alterou", "protestou" e "rejeitou" (mais detalhes abaixo).

**No campo headers atualmente é aceito apenas uma propriedade.

***O campo headers adicionais só devera ser utilizado caso você precise informar mais de um header (nesse caso um header devera ser informado no campo headers e o restante no campo headers adicionais)

Os Eventos, que são momentos em que a requisição são enviadas, podem ser:

• Registrou: Ao recebermos do banco o arquivo de retorno, e este altere a situação do boleto para "Registrado", esta notificação será ativada;
• Liquidou: Disparado ao recebermos o retorno e os boletos tiverem a situação atualizada para "Liquidado";
• Baixou: Disparado ao recebermos a confirmação da Baixa do Boleto;
• Alterou: Disparado quando o arquivo de retorno possuir informações que atualizem a data de vencimento e/ou valor dos boletos e demais alterações enviadas pelo banco, porém, com o boleto permanecendo com a mesma situação;
• Rejeitou: Disparado quando o boleto voltar do banco como "Rejeitado".
• Protestou: Disparado quando o boleto voltar do banco como situação de protesto, "Incluído cartório".

Exemplo:

{
 "ativo":true,
 "url": "https://minha-api.com.br/callback",
 "data_ativacao": "2025-10-22",
 "eventos": {
    "registrou": true,
    "liquidou": false,
    "baixou": false,
    "protestou": false,
    "alterou": false,
    "rejeitou": false
 },
 "headers": {
   "auth": "meu-token"
 },
 "headers_adicionais": [
   {
    "adicional-1": "token-adicional-1",
    "adicional-2": "token-adicional-2" 
   }
 ]
}

Retorno

Exemplo de retorno:

 Exemplo de retorno com erro:

O que sua API irá receber?

Após configurar os WebHooks, nossa API passará enviar para a sua requisições POST contendo jsons com as informações dos títulos que sofreram conciliação bancária.

Estes jsons serão enviados no seguinte formato:

"tipoWH": onde estará identificado o tipo da notificação que foi enviada;

"dataHoraEnvio": que identificará a data e hora em que a notificação foi gerada

"titulo": o conteúdo deste campo irá variar de acordo com o tipo do json, ele trará informações para identificação do boleto de acordo com cada tipo de notificação.

Segue abaixo alguns exemplos de json que seu sistema irá receber para cada uma das notificações Webhook:

Registro:

{
    "body": {
        "tipoWH": "notifica_registrou",
        "dataHoraEnvio": "21/09/2018 03:59:44",
        "titulo": {
            "situacao": "REGISTRADO",
            "idintegracao": "a1a1a1a1a1a1",
            "TituloNossoNumero": "10",
            "TituloMovimentos": [
                {
                    "codigo": "02",
                    "mensagem": "Movimento: Entrada Confirmada",
                    "data": "21/09/2018 00:00:00",
                    "taxa": "0,00",
                    "ocorrencias": [
                        {
                            "codigo": "A4",
                            "mensagem": "Sacado DDA"
                        }
                    ]
                }
            ]
        },
        "CpfCnpjCedente": "55965999000103"
    },
    "kind": "webhook",
    "method": "POST",
    "url": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
    "headers": {
        "Content-Type": "application/json",
        "Authorization": "b1b1b1b1b1b1b1b1b1b"
    }
}

Liquidação:

{
    "body": {
        "tipoWH": "notifica_liquidou",
        "dataHoraEnvio": "27/09/2018 03:59:44",
        "titulo": {
            "situacao": "LIQUIDADO",
            "idintegracao": "a1a1a1a1a1a1",
            "PagamentoData": "20/09/2018",
            "TituloNossoNumero": "10",
            "PagamentoValorPago": "50,00",
            "PagamentoDataCredito": "20/09/2018",
            "PagamentoValorAcrescimos": null,
            "PagamentoValorMulta": null,
            "PagamentoValorJuros": null,
            "PagamentoValorDesconto": null,
            "TituloMovimentos": [
                {
                    "codigo": "02",
                    "mensagem": "Movimento: ENTRADA CONFIRMADA COM POSSIBILIDADE DE MENSAGEM",
                    "data": "17/09/2018 00:00:00",
                    "taxa": "0,00",
                    "ocorrencias": {}
                }
            ]
        },
        "CpfCnpjCedente": "123456789"
    },
    "kind": "webhook",
    "method": "POST",
    "url": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
    "headers": {
        "Content-Type": "application/json",
        "token-sh": "b1b1b1b1b1b1b1b1b1b",
        "cnpj-sh": "c1c1c1c1c1c1c1c1c1c",
        "authorization": "d1d1d1d1d1d1d1d1d1d"
    }
}

Baixa:

{
    "body": {
        "tipoWH": "notifica_baixou",
        "dataHoraEnvio": "22/09/2018 03:42:51",
        "titulo": {
            "situacao": "BAIXADO",
            "idintegracao": "a1a1a1a1a1a1",
            "TituloNossoNumero": "10",
            "TituloMovimentos": [
                {
                    "codigo": "02",
                    "mensagem": "Entrada confirmada",
                    "data": "22/09/2018 00:00:00",
                    "taxa": "0,00",
                    "ocorrencias": {}
                }
            ]
        },
        "CpfCnpjCedente": "123456789"
    },
    "kind": "webhook",
    "method": "POST",
    "url": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
    "headers": {
        "Content-Type": "application/json",
        "WGX-API-KEY": "b1b1b1b1b1b1b1b1b1b"
    }
}

Rejeição:

{
  "body":{
        "tipoWH": "notifica_rejeitou",
        "dataHoraEnvio": "27/09/2018 13:58:27",
        "titulo": {
            "situacao": "REJEITADO",
            "idintegracao": "a1a1a1a1a1a1",
            "TituloNossoNumero": "10",
            "TituloMovimentos": []
        },
        "CpfCnpjCedente": "123456789"
    },
    "kind": "webhook",
    "method": "POST",
    "url": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
    "headers": {
        "Content-Type": "application/json",
        "auth": "b1b1b1b1b1b1b1b1b1b"
    }
}

Alteração:

{
  "body":{
        "tipoWH": "notifica_alterou",
        "dataHoraEnvio": "25/09/2018 04:13:24",
        "titulo": {
            "situacao": "REGISTRADO",
            "TituloValor": "50,00",
            "TituloDataVencimento": "25/10/2018",
            "idintegracao": "a1a1a1a1a1a1",
            "TituloNossoNumero": "10",
            "TituloMovimentos": [
                {
                    "codigo": "02",
                    "mensagem": "Entrada confirmada",
                    "data": "17/07/2018 00:00:00",
                    "taxa": "0,00",
                    "ocorrencias": {}
                }
            ]
        },
        "CpfCnpjCedente": "123456789"
    },
    "kind": "webhook",
    "method": "POST",
    "url": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
    "headers": {
        "Content-Type": "application/json",
        "Authorization": "b1b1b1b1b1b1b1b1b1b"
    }
}

Exemplo de implementação de um servidor de recebimento basico:

const express = require('express');
const bodyParser = require('body-parser');

const app = express();
app.use(bodyParser.json());

app.post('/webhook', (req, res) => {
// Neste ponto você faz o mapeamento dos dados
const payload = req.body;

// Exemplo de ação com base nos dados recebidos
console.log('Recebido um novo webhook:');
console.log(payload);

// Envie uma resposta de sucesso ao emissor do webhook
res.sendStatus(200);
});

// Inicie o servidor na porta desejada
const port = 3000;
app.listen(port, () => {
console.log(`Servidor de webhook iniciado na porta ${port}`);
});

Neste exemplo, usamos o framework Express.js para criar o servidor HTTP. Estamos usando o middleware body-parser para analisar o corpo das solicitações como JSON.

Definimos uma rota POST /webhook que será o ponto de extremidade para receber os Webhooks. Dentro desta rota, você pode processar os dados recebidos como necessário. Neste exemplo, estamos simplesmente imprimindo o payload recebido no console.

Detalhes:

Após receber o json em seu sistema, recomendamos que você capture o idintegracao presente na requisição, e na sequência faça uma consulta pelo boleto, para que nesta consulta você obtenha a resposta completa, com todos os campos presentes em nosso banco de dados, para assim deixar seu sistema 100% atualizado com as informações que vieram do banco.