Notificações

Webhook de eventos

A API de crédito permite construir integrações a partir da assinatura de eventos públicos.

Quando um evento acontece, a API é capaz de notificar os assinantes através de um POST HTTP configurado no nosso serviço de webhooks.

É possível assinar todos ou cada um dos eventos públicos de crédito. Não existe limite de webhooks por assinantes.

Assinaturas

Ao assinar os eventos de crédito no serviço de webhooks, o assinante receberá uma chave privada confidencial. Essa chave deve ser usada para validar as notificações recebidas, para garantir que a origem da informação é confiável.

Atenção: Se o método de assinatura for pela fila de eventos ao invés do Webhook, os metadados irão vir dentro de uma estrutura maior

{
    "EventName": "Payment", // Entidade
    "EventVersion": 2, // Versao da entidade
    "Id": "01GW11SZD6GYJF817SM6GQDTY2", // Identificador da notificação (OLID)
    "EventKey": "jqtar32bh95558na2s6dxhd7f", // Identificador unico do evento
    "Timestamp": "2020-04-14T17:54:10.727031Z", // Data do disparo do evento
    "Metadata": { // Os dados em si do evento
       // O Objeto estará aqui dentro
    },
    "ActionName": "Created", // O que ocorreu com a entidade
    "EventSource": "CreditApi" // De onde o evento foi disparado
}

Um assinante pode configurar uma ou mais assinaturas, basta informar:

Notificações

As notificações são realizadas utilizando o método POST HTTP e segue o padrão abaixo:

{
  "ActionName": "Settled",
  "EventName": "Loan",
  "EventKey": "jrkuiop79879873987423",
  "Id": "01GW11SZD6GYJF817SM6GQDTY2",
  "EventVersion": 1,
  "EventSource": "CreditApi",
  "Timestamp": "2020-02-03T18:59:12.7436071Z",
  "Metadata": { ... }    
}

📘

Validação de assinatura

Para validar a origem da informação o assinante deve fazer o HMAC do corpo da mensagem recebida com a função SHA256, usando a sua chave privada.

O valor resultante deve ser igual ao recebido no header Credit-Webhook-Authorization

Veja abaixo um exemplo de implementação da validação da assinatura usando .NET Core e C#

using System;
using System.Security.Cryptography;
using System.Text;

public string ComputeRequestBodySha256HashString(string requestBody, string privateKey)
{            
  var secret = Encoding.ASCII.GetBytes(privateKey);
  var inputStream = Encoding.ASCII.GetBytes(requestBody);

  using (var hasher = new HMACSHA256(secret))
  {
    var hash = hasher.ComputeHash(inputStream); 

    return $"sha256={BitConverter.ToString(hash).Replace("-", "")}";
  }
}

📘

Boas práticas de integração

Recomendamos algumas boas práticas para construir uma integração baseada em webhooks, com relação a eventuais falhas de comunicação e retentativas de envio

Tipos de eventos e ações

Veja abaixo a lista de eventos publicados pela API de crédito

📘

Firewall e configurações de rede

Para receber as notificações, o assinante precisa estar apto a receber mensagens HTTP das seguintes origens: