Introdução aos Webhooks

Webhooks permitem que a BonifiQ chame diretamente a sua API. Isso evita que você tenha que fazer chamadas periódicas à API da BonifiQ, evitando gasto de recursos e permitindo manter bases de dados atualizadas e comunicações externas.

Como funciona

Antes de mais nada é necessário cadastrar o endpoint que será chamado. Você fazer quantos cadastros forem necessários. Esse cadastro é relacionado a um ou mais tópicos.

Cada tópico corresponde a um tipo de evento que será enviado ao seu endpoint e corresponde, também, a um payload específico.

Um payload é o corpo da requisição que contém detalhes do evento. Por exemplo: no caso do tópico Ponto Adicionado, você deve esperar receber a quantidade de pontos. Os detalhes de cada Payload seguem abaixo.

É esperado que seu endpoint receba a requisição como um POST. Deverá haver uma resposta HTTP com status 200.

O endpoint deverá responder em no máximo 30 segundos, caso contrário será considerado inválido.

Cadastrar endpoint

O primeiro passo para utilizar o sistema de Webhook é cadastrar o endpoint que será chamado. Para isso:

- Vá no menu "API"

- Clique na aba "Webhook" 

- Clique no botão "+ CREDENCIAL API"

- Escolha "Webhook"

Agora basta preencher os campos do endpoint:

- Ativado: Marque para permitir que os eventos sejam enviados para o endpoint

- URL: Endereço do endpoint que irá receber as chamadas. O endereço precisa ser acessível publicamente.

- Tópicos: Quais eventos devem gerar chamadas no endpoint cadastrado

- E-mail Técnico: Caso ocorram muitos erros no envio dos webhooks esse e-mail será acionado para realizar a correção.

- Cabeçalhos: Opcional, permite que sejam enviados um ou mais cabeçalhos HTTP, enviados na requisição. Permite que você cadastre tokens de acesso, para garantir que a chamada realmente foi originada pela BonifiQ.

Tópicos

A BonifiQ irá enviar para o endpoint os eventos relacionados aos tópicos selecionados no cadastro. Cada tópico possui uma utilização específica, com um payload específico.

Ponto Adicionado  

Ponto Removido 

Ponto Atualizado 

Comunicações 

Payload

Por padrão, a BonifiQ envia um body na requisição para o seu endpoint. Esse corpo possui algumas propriedades padrão para todas as requisições.

{
   "Uuid":"4834c95e-84f7-485e-90de-09353df57fd3",
   "Timestamp":"2024-03-01T13:16:11.396371",
   "Topic":0,
   "TopicName":"Point_Add",
   "Payload":{
      "Points":200,
      "PointType":0,
      "PointAction":1,
      "Customer":{
         "Email":"teste@bonifiq.com.br",
         "Id":"152740926",
         "Name":"Teste Nivel Base"
      },
      "PointsBalance":{
         "PointsBalance":300,
         "CashbackBalance":210
      },
      "PointId":4740
   }
}