Validar a assinatura do webhook

Cabeçalho atual

O contrato público usa x-azentech-webhook-signature. A Azentech calcula o valor em duas codificações:

Calcula o HMAC-SHA256 do JSON compacto com o segredo da inscrição.

Representa o digest como caracteres hexadecimais minúsculos.

Codifica esses caracteres ASCII em Base64.

Isso difere de codificar os 32 bytes brutos do HMAC em Base64.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyAzentechSignature(rawBody, received, secret) {
  if (typeof received !== "string") return false;

  const hexDigest = createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  const expected = Buffer.from(hexDigest, "ascii").toString("base64");
  const actualBytes = Buffer.from(received, "utf8");
  const expectedBytes = Buffer.from(expected, "utf8");

  return actualBytes.length === expectedBytes.length
    && timingSafeEqual(actualBytes, expectedBytes);
}

Use o corpo bruto recebido. Não converta o JSON em objeto e não o serialize novamente antes da validação.

Cabeçalho legado

Quando o estabelecimento está configurado para o emissor legado, o cabeçalho é Signature. Esse modo não usa o segredo da inscrição. Ele deriva um segredo com uma semente de plataforma e aplica um segundo HMAC:

derived = Base64(hex(HMAC-SHA256(json_compacto, platform_seed)))

Signature = hex(HMAC-SHA256(json_compacto, derived))

O valor final usa caracteres hexadecimais minúsculos sem Base64.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyLegacySignature(rawBody, received, platformSeed) {
  if (typeof received !== "string") return false;

  const firstHex = createHmac("sha256", platformSeed)
    .update(rawBody)
    .digest("hex");
  const derived = Buffer.from(firstHex, "ascii").toString("base64");
  const expected = createHmac("sha256", derived)
    .update(rawBody)
    .digest("hex");
  const actualBytes = Buffer.from(received, "utf8");
  const expectedBytes = Buffer.from(expected, "utf8");

  return actualBytes.length === expectedBytes.length
    && timingSafeEqual(actualBytes, expectedBytes);
}

Confirme com a Azentech os parâmetros de validação quando usar esse modo. Os valores nos exemplos são nomes descritivos, não credenciais.

Não tente validar Signature com o segredo da inscrição. Confirme com a Azentech qual modo está ativo antes de trocar o cabeçalho aceito em produção.

Primeiros passos

Pagamentos

Webhooks

Validar a assinatura do webhook

Cabeçalho atual

Cabeçalho legado

​Cabeçalho atual

​Cabeçalho legado

Cabeçalho atual

Cabeçalho legado