Verificar assinaturas de webhook (HMAC)

A verificação da assinatura do webhook usando HMAC (Hash-based Message Authentication Code) garante que os webhooks enviados ao seu servidor sejam realmente originários da Yuno e não tenham sido interceptados ou modificados durante a transmissão. Isso adiciona uma camada extra de segurança além dos métodos de autenticação como o OAuth.

Enquanto o OAuth fornece autenticação (verificação de quem está enviando a solicitação), as assinaturas HMAC fornecem:

Integridade dos dados: Confirma que a carga do webhook não foi adulterada
Autenticidade: Verifica se o webhook vem genuinamente da Yuno
Proteção: Protege contra ataques man-in-the-middle e ataques de repetição
Conformidade: Atende aos requisitos de segurança para lidar com dados de pagamento confidenciais

Como funcionam as assinaturas HMAC

Quando o Yuno envia um webhook para seu servidor:

Geração de assinatura: A Yuno cria uma assinatura HMAC fazendo o hash da carga útil do webhook com a chave secreta do cliente usando o algoritmo SHA-256
Inclusão de cabeçalho: A assinatura está incluída no x-hmac-signature Cabeçalho HTTP
Verificação: Seu servidor extrai a assinatura do cabeçalho, recria-a usando a mesma carga útil e chave secreta e, em seguida, compara
Validação: Se as assinaturas corresponderem, o webhook é autêntico e inalterado

Configuração

Para ativar a verificação de assinatura HMAC, marque Usar autenticação HMAC ao criar ou editar um webhook no painel do Yuno.

Consulte Configurar webhooks para obter instruções passo a passo sobre como acessar o painel de configuração do webhook.

O que muda com o HMAC

Quando a verificação de assinatura HMAC está ativada, os webhooks do Yuno incluem um x-hmac-signature cabeçalho HTTP. A carga útil JSON do webhook permanece inalterada.

Exemplo de solicitação de webhook com HMAC

POST /your-webhook-endpoint HTTP/1.1
Host: your-server.com
Content-Type: application/json
x-api-key: your-api-key
x-secret: your-secret
x-hmac-signature: K7gNU3sdo+OL0wNhqoVWhr3g6s1xYv72ol/pe/Unols=

{
  "type": "payment",
  "type_event": "payment.purchase",
  "account_id": "2c05976d-1234-1234-1234-6421883de48d",
  "retry": 0,
  "version": 2,
  "data": {
    "payment": {
      "id": "a546c566-1703-4fba-b334-c46e89bc97f7",
      "status": "SUCCEEDED"
    }
  }
}

Como funcionam as assinaturas HMAC

Configuração

O que muda com o HMAC

Exemplo de solicitação de webhook com HMAC

Documentação relacionada