Webhooks são recursos que permitem a comunicação instantânea entre duas aplicações quando ocorre um evento determinado, sem exigir intervenções externas, e possibilitam o envio de notificações.

Em nosso cenário, é possível parametrizar o destino de recebimento das notificações via webhook, armazenar e consultar os eventos emitidos e seus respectivos status e emitir a requisição http para a URL parametrizada.

Implementação

Para utilizar os webhooks, o receptor deverá construir uma API e disponibilizar a URL do endpoint para recebimento dos eventos.

As mensagens são transmitidas utilizando exclusivamente o método HTTP POST, então é essencial que o endpoint da API esteja configurado para suportar somente esse método.

Para confirmar à Parcelamos Tudo que a mensagem foi recebida com sucesso, o endpoint deve responder com um código de status 2xx. Qualquer outro código será interpretado como uma falha no recebimento.

Se houver uma falha no recebimento, o sistema fará duas novas tentativas de envio, com intervalos de 10 e 45 segundos entre cada uma. Após essas tentativas, o envio da requisição será encerrado. Para realizar uma nova tentativa, será necessário utilizar nosso endpoint novamente.

Headers da requisição

A aplicação cliente receberá mensagens via chamadas HTTP, enviadas pela plataforma da Parcelamos Tudo. Nestas solicitações, serão incluídos os seguintes headers:

idempotency-key: A chave de idempotência identifica a comunicação com o receptor e garante que uma mesma requisição não seja processada duas vezes. Essa chave não faz parte da assinatura HMAC.
authorization: Neste header, será enviada a assinatura HMAC. Essa assinatura é uma representação SHA-256 codificada em base64 e será utilizada pela aplicação cliente para verificar a autenticidade da mensagem recebida.

Assinatura HMAC

É necessário adotar a assinatura HMAC(Hash-based Message Authentication Code) como meio de autenticação de sua API para garantir a procedência das informações e proteger o endpoint.

Para gerar a assinatura HMAC, é necessário ter uma chave secreta (private_key) compartilhada entre o emissor e o receptor, a qual deve ser mantida em segredo. Utilizando essa chave, é criado um objeto HMAC com o algoritmo SHA-256. Em seguida, o payload é atualizado e o valor do hash é calculado. Esse valor, em formato hexadecimal, representa a assinatura HMAC, que é utilizada para verificar a autenticidade dos dados transmitidos.

O receptor da mensagem deve calcular a assinatura HMAC usando a mesma chave secreta e os mesmos parâmetros de criação. Em seguida, compara-se a assinatura HMAC recebida com a assinatura esperada. Se forem idênticas, os dados são considerados autênticos e válidos.

Exemplo de código

const { createHmac } = require('crypto');

const received_hmac = 'f77c46e0c5f25b5c1bc5c1afca2b80260a45c36d98717f914bccdaa3e10997fc';
const private_key_origin = '8b7cfee8-85c1-4025-b3c2-d766457d4626';
const payload_string = `{"context":"order","event":"order.created","establishment":"4e0ec338-b344-4dba-92d7-5cf4923408bc","timestamp":"2025-02-04T13:16:42.784Z","version":"1","data":{"id_order":"ord_2sZtcID67yMYafKJu1JmUJdzqPR","id_merchant":"mer_108EjtXWEQSEUZ","status":"authorized","type":"credit_card","external_reference_id":null,"description":null,"customer":{"name":"William Batz","document":"63303757046","ip":null},"currency":"BRL","amount":150,"amount_captured":0,"amount_refund":0,"amount_installment":150,"installment_number":1,"amount_interchange":0,"nsu_tef":"vqdzhutq8jsu","nsu_acquirer":"twyfuwc1","nsu_cancellation":null,"card":{"brand":"visa","first_digits":"476112","last_digits":"0148","exp_month":"12","exp_year":"2034","holder_name":"NOME CARTD","holder_document":"25953254180"},"soft_description":"Teste","authorization_code":"de27d006-2fda-48c2-8c3b-e26f059e600a","created_at":"2025-02-04T13:16:42.212755Z","updated_at":"2025-02-04T13:16:42.729904Z","provider_code":"8fca7a3b-d858-4968-bda3-3ccc88f52857","capture":{"method":"online","partner":"internal"},"completed_at":null,"canceled_at":null,"establishment_id":"4e0ec338-b344-4dba-92d7-5cf4923408bc"}}`;

const signature = createHmac('sha256', private_key_origin).update(payload_string).digest('hex');

if (received_hmac == signature) {
  console.log('Chave HMAC válida');
} else {
  console.log('Chave HMAC inválida');
}

Com a URL do endpoint e a assinatura HMAC implementada, será possível: