Pré Requisitos
É 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.
:::caution
É 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 |
---|---|---|
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:
{
"reference": "123456789",
"status": "executed",
"amount": 150.0,
"processingDate": "2024-06-08T14:15:22Z"
}