Estrutura Básica dos Webhooks

Estrutura

Os eventos Hiperbanco são organizados em listas e enviados ao parceiro no formato JSON. Cada evento possui a seguinte estrutura:

Nome	Tipo	Descrição
entityId	string	Identificador da entidade emissora do evento. Portanto, ele dependerá do contexto de sua emissão. Exemplo: eventos de Pix utilizam como identificador o authenticationCode do Pix.
companyKey	string	Chave que identifica o parceiro dentro do Hiperbanco.
idempotencyKey	string	Valor retornado para evitar eventos duplicados (em formato UUID).
context	string	Contexto em que o evento foi criado. Os possíveis contextos estão listados mais adiante nesta documentação.
name	string	Nome descritivo que identifica a operação realizada.
timestamp	string	Data e a hora em que o evento ocorreu, no formato ISO 8601 - UTC.
correlationId	string	Identificador que correlaciona todo o fluxo das operações.
version	string	Versão do evento.
metadata	object	Informações adicionais pertinentes ao contexto, representadas através de pares de chave e valor. Tais informações não fazem parte explicitamente da transação e são sujeitas à variação. Por exemplo, o tempo de solicitação e o tempo de resposta da operação.
data	object	Entidade relacionada ao ID, que varia conforme o evento. Por exemplo, quando se trata de um evento de conta, o data trará dados da estrutura de uma conta.

⚠️
Importante
Recomendamos que os parceiros observem a versão do evento a ser utilizado, pois, de forma a melhorar a experiência dos seus clientes, o Hiperbanco está constantemente evoluindo seus produtos.

[
   {
      "entityId": "Id of the entity that raised the event",
      "companyKey": "Company Key of the entity that raised the event",
      "context": "Context of the service that raised the event",
      "name": "Event name",
      "timestamp": "Date when the event was raised",
      "correlationId": "For tracing",
      "version": "1.0",
      "metadata": {
         "key": "Complement event info"
      },
      "data": {
         "Bar": "Foo"
      }
   }
]

Exemplos

[
   {
      "entityId":"16d9ce8d-bf54-4433-ac4e-0000000000",
      "companyKey":"HIPERBANCO",
      "idempotencyKey":"3b5d8309-cb7f-4b0d-8d35-0000000000",
      "context":"Ted",
      "name":"TED_CASH_IN_WAS_RECEIVED",
      "timestamp":"2022-01-11T13:06:24.2559021Z",
      "correlationId":"7ab145b5-f0a1-42af-b187-8dcb670b962c",
      "metadata":null,
      "data":{
         "authenticationCode":"16d9ce8d-bf54-4433-ac4e-0000000000",
         "amount":{
            "value":0.01,
            "currency":"BRL"
         },
         "recipient":{
            "document":{
               "value":"09992220074",
               "type":"CPF"
            },
            "type":"Maria Quitéria de Jesus",
            "name":"string",
            "account":{
               "branch":"0001",
               "number":"540108",
               "bank":{
                  "ispb":"13140088",
                  "code":"332"
               }
            }
         },
         "channel":{
            "name":"SPB",
            "sender":{
               "document":{
                  "value":"47742663023",
                  "type":"CPF"
               },
               "type":"Customer",
               "name":"Nísia Floresta",
               "account":{
                  "branch":"0001",
                  "number":"15164",
                  "bank":{
                     "ispb":"13140088"
                  }
               }
            },
            "controlNumber":"STR2022011100000000000"
         },
         "createdAt":"2022-01-09T13:06:24.2240368Z"
      }
   }
]

Contextos

Nome	Descrição
Boleto	Agrupa todos os eventos relacionados a boletos, como emissão, cancelamento, compensação etc.
Contas (Account)	Agrupa todos os eventos relacionados a acordos legais, abertura e encerramento de contas (por solicitação do cliente, parceiro ou Hiperbanco), assim como eventos referentes a bloqueio/desbloqueio judicial.
Envio de documentos de Onboarding (Document)	Agrupa todos os eventos relacionados ao recebimento e ao processamento de imagens para Onboarding.
Pagamento de contas (Payment)	Agrupa todos os eventos relacionados a pagamentos de contas, como criação, recebimento, confirmação e cancelamento do pagamento, assim como falha na transação.
Pessoa física (Customer)	Agrupa todos os eventos relacionados a Onboarding e Offboarding de pessoa física.
Pessoa jurídica (Business)	Agrupa todos os eventos relacionados a Onboarding e Offboarding de pessoa jurídica (MEI, EI, EIRELI ou SLU, LTDA, S.A. e TS).
Pix e DICT	Agrupa todos os eventos relacionados a cash-in e cash-out, devoluções (refunds), QR Codes Pix, DICT, pedidos de portabilidade e reivindicação de chaves Pix.
TED	Agrupa todos os eventos relacionados a cash-in, cash-out e devoluções (refunds) via TED.