署名検証

HMAC-SHA256署名を使って、受信したWebhookが本当にJammから送信されたことを検証します。

Jammが送信するすべてのWebhookにはHMAC-SHA256署名が含まれます。ペイロードを信頼する前に、必ず署名を検証してください。これにより、イベントがJammから送信され、送信中に改ざんされていないことを確認できます。

署名の仕組み

Jammは署名を次のように計算します：

signature = "sha256=" + HMAC_SHA256(client_secret, content_bytes)

ここで：

• client_secretはオンボーディング時に発行されるClient Secretです。
• content_bytesはWebhookボディで配信されるcontentフィールドのバイト列そのものです。

⚠️ 重要: 署名はペイロード自体のsignatureフィールドで配信されます — 署名用のHTTPヘッダーはありません。署名はエンベロープ全体ではなくcontentフィールドのみに対して計算されます。

SDKでの検証

contentオブジェクトをverifyに渡し、signatureはペイロードから取得します。検証に失敗すると例外がスローされます。その場合はペイロードを処理しないでください。

import jamm from "@jamm-pay/node-sdk";

// body = パース済みのWebhook JSON: { id, signature, event_type, content, created_at }
jamm.webhook.verify({ 
  data: body.content, 
  signature: body.signature 
});

// 検証成功後にのみパースします（parse はエンベロープ全体を受け取ります）:
const event = jamm.webhook.parse({ data: body });

💡 同等のヘルパーは Ruby, PHP, and Java SDKでも利用できます。

手動での検証

SDKを使用できない場合は、contentフィールドを自分でHMACしてください：

import crypto from "crypto";

// rawContent = 受信した `content` フィールドのバイト列／文字列そのもの。
const expected = "sha256=" + crypto
  .createHmac("sha256", clientSecret)
  .update(rawContent)
  .digest("hex");

if (
  expected.length !== payload.signature.length ||
  !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(payload.signature))
) {
  throw new Error("Invalid signature");
}

🔒 セキュリティ上の注意: 定数時間比較（timingSafeEqual）を使用してください — 通常の===比較はタイミング情報を漏らし、攻撃者による署名偽造を助けるおそれがあります。