É essencial que o parceiro estabeleça pelo menos um ponto de extremidade (endpoint) para receber os eventos do Sistema.

Todas as mensagens enviadas utilizam o método HTTP POST, portanto, é imperativo que o endpoint da API do parceiro também utilize esse método.

Para indicar ao Sistema que a mensagem foi recebida com êxito, o endpoint deve responder com um código de status no intervalo de 200 a 299. Qualquer outra resposta será considerada como um recebimento sem sucesso.

CUIDADO

É importante ressaltar que o parceiro deve adotar a assinatura HMAC como meio de autenticação de sua API. Somente essa medida pode proteger o endpoint de ataques de aplicações maliciosas.

Chave de assinatura HMAC

A assinatura HMAC é um algoritmo utilizado para assinar mensagens, garantindo a autenticidade dos eventos enviados e protegendo o endpoint do parceiro contra ataques de aplicações maliciosas.

A aplicação cliente receberá mensagens via chamadas HTTP. Nestas chamadas, são enviados os seguintes headers necessários para que a aplicação cliente possa gerar a assinatura HMAC:

HEADER	DESCRIÇÃO	EXEMPLO
signature	Contém a assinatura HMAC. Esse valor é utilizado pela aplicação cliente para validar a mensagem recebida.	904cfc67b1354d5b859c4554de2640941d8d23f5b0d586e38bcdd93648f73174

Utilizamos o algoritmo hmac para a geração da assinatura. O processo de formação da assinatura é o seguinte:

Obter a chave de assinatura junto a Preâmbulo Bank.

Transformar o corpo da requisição recebida em uma string no formato JSON.

Utilizar o algoritmo HMAC com SHA-256 para gerar a chave.

Comparar o valor gerado por este algoritmo com o valor enviado no cabeçalho signature. Ambos devem ser iguais.

O algoritmo criptográfico utilizado para geração no webhook é o SHA-256.

SHA-256 significa "algoritmo de hash seguro de 256 bits" e é utilizado para segurança criptográfica. Os algoritmos de hash criptográficos produzem hashes irreversíveis e únicos. Quanto maior o número de hashes, menor a chance de dois valores criarem o mesmo hash.

Corpo da Requisição

NOME	TIPO	DESCRIÇÃO
type	`string`	Tipo do evento. Valores possíveis: `pix.sent` `pix.failed` `pix.received` `pix.refund-received` `pix.refund-sent`
reference	`string`	Código interno do cliente.
status	`string`	valores possíveis: `pending` `scheduled` `processing` `executed` `failed` `partially_refunded` `fully_refunded` `canceled`
amount	`number <double>`	Valor da operação.
processingDate	`string <date-time>`	Data e hora de processamento.

Exemplo:

Webhook

Chave de assinatura HMAC#

Corpo da Requisição#

Chave de assinatura HMAC

Corpo da Requisição