Notificações via webhook

Caso o cliente opte por receber notificações automaticamente após o processamento das intruções, ele deverá fornecer um endpoint https, conforme descrito a seguir, para que a Funcional configure o sistema de notificações e consiga efetuar seu envio do resultado do processamento.

Endpoint do cliente

O endpoint https fornecido pelo cliente deve estar preparado para receber requisições POST contendo o seguinte objeto JSON :

{
  "id": "123456",
  "companyIdentity": "12345678000190",
  "holderIdentity": "01234567890",
  "beneficiarySequentialNumber": 0,
  "beneficiaryIdentity": "01234567890",
  "cardNumber": "01234567890123456",
  "registration": "0000000123",
  "objectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxx",
  "status": 2,
  "statusMessage": ""
}

Observação

As propriedades beneficiaryIdentity, cardNumber, registration e objectId só estarão preenchidas se elas forem informadas na instrução enviada para a mutation, caso contrário elas estarão com o valor null

Este objeto JSON contém as mesmas propriedades descritas no BeneficiaryProcessingStatusType que é retornado pela query getProcessingStatus.

O valor da propriedade status desse objeto indicará o resultado do processamento da instrução, sendo atribuido a ela o valor 2 ( SUCCESS ) ou 3 ( ERROR ). Caso o valor dessa propriedade seja 3 ( ERROR ), a propriedade statusMessage estará preenchida com uma descrição do erro ocorrido.

Segurança

Além da segurança do transporte ser garantida pelo https o sistema de notificações da Funcional poderá, à desejo do cliente, utilizar mais dois recursos para aumentar a segurança no envio das requisições para o seu endpoint:

• Authorization header
• HMAC SHA256 BODY SIGNATURE

Authorization header

Ao configurar o endpoint do serviço do cliente no sistema da Funcional, poderemos registrar as credenciais de acesso ( login e senha ) e enviá-las no header authorization: Basic de todas as requisições ao endpoint do cliente.

Exemplo de header authorization:

content-type: application/json
authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

HMAC SHA256 BODY SIGNATURE

Ao configurar o endpoint do serviço do cliente no sistema da Funcional, poderemos registrar uma chave secreta para assinar o objeto JSON ( body ) da requisição e enviar a assinatura no header x-fht-webhook-signature da requisição ao endpoint do cliente e ao recebê-la, o sistema do cliente, de posse da mesma chave poderá verificar se a assinatura do conteúdo recebido é válida.

Exemplo de header x-fht-webhook-signature:

content-type: application/json
x-fht-webhook-signature: RbO8MDgJ0z5ydolXJiB0Y/k6O6ApbUZQWZjT2fUO+Zo=

Caso utilize os dois recursos de segurança:

content-type: application/json
authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
x-fht-webhook-signature: RbO8MDgJ0z5ydolXJiB0Y/k6O6ApbUZQWZjT2fUO+Zo=

Exemplo de código para validação de assinatura:

//javascript
const crypto = require("crypto");

const secretKey = "chave secreta compartilhada com o cliente";

export function verifySignature(request) {
  const signature = request.headers["x-fht-webhook-signature"];
  const computedSignature = crypto
    .createHmac("sha256", secretKey)
    .update(JSON.stringify(request.body))
    .digest("base64");
  return computedSignature === signature;
}