Webhookのセキュリティ

お知らせ：当社は、お客様により充実したサポート情報を迅速に提供するため、本ページのコンテンツは機械翻訳を用いて日本語に翻訳しています。正確かつ最新のサポート情報をご覧いただくには、本内容の英語版を参照してください。

Zoho Sign では、Webhook のセキュリティを確保するために HMAC-SHA 256（SHA 256 を用いたハッシュベースメッセージ認証コード）を使用するオプションを提供しています。これは Webhook の真正性と完全性を保証するための業界標準のハッシュ方式です。Webhook を HMAC で保護すると、次の点を検証できます。

Webhook リクエストが Zoho Sign から送信されたものかどうか（シークレットキーは Zoho Sign と受信アプリケーションのみが知っている必要があります）。
Webhook のコンテンツが途中で改ざんされていないかどうか（完全性）。

Zoho Sign における Webhook セキュリティの仕組み

Zoho Sign から Webhook が送信されると、HMAC 署名が X-ZS-Webhook-署名 という名前でリクエストヘッダーに含まれます。Webhook リクエストを受信したアプリケーションは、同じシークレットキーを使用して HMAC 署名を生成し、リクエストヘッダーに含まれる値と比較します。値が一致すればデータは正当であり、一致しない場合はデータが改ざんされています。

HMAC 署名の生成

Zoho Sign は、Webhook ペイロードの内容に対して HMAC-SHA256 アルゴリズムを使用して署名を計算し、その結果を base64 形式にエンコードしてリクエストヘッダーに送信します。以下はサンプルデータを用いた説明です。

ペイロードの内容	{{'requests':{'request_name':'テスト名前'},'通知':{'operation_type':'RequestSigningSuccess'}}
secret_key	thisisthesamplekeyfortestingpurposes
base64encode(HMAC SHA-256(ペイロードの内容+secret_key))	drbSrM4H816RYKpZiRBLddUa0yHaTrwjtY04sIZFZus=

この Webhook リクエストヘッダー（HMAC ヘッダー）がどのように表示されるかを示す画像は次のとおりです。

受信アプリケーションでの HMAC 署名の検証

JSON 形式で読み込む際にキーの順序が変わらないよう、ペイロードの内容は文字列として読み取る必要があります。
シークレットキーを使用してペイロードの内容の HMAC SHA-256 ハッシュを計算し、その結果を base64 エンコードします。
手順 2 で得られた値と、受信した HMAC ヘッダー（X-ZS-Webhook-署名）の値を比較します。値が一致しない場合は、その Webhook リクエストを拒否してください。

HMAC 署名を検証するための Java コードサンプル

非公開 static String verifyHmacHash(String secretKey, String ペイロードの内容, String hmacHash) throws Exception
{
String macAlgoName = 'HmacSHA256';
byte[] secretKeyBytes = secretKey。getBytes(StandardCharsets。UTF_8);
Mac mac = Mac。getInstance(macAlgoName);
SecretKeySpec keySpec = 新規 SecretKeySpec(secretKeyBytes, mac。getAlgorithm());
mac。init(keySpec);
byte[] macData = mac。doFinal(ペイロードの内容。getBytes(StandardCharsets。UTF_8));
String calculatedHmac = java。util。Base64。getEncoder().encodeToString(macData);
if(hmacHash。equals(calculatedHmac))
{
System。出力。println('Hashes が一致しました。Webhook ペイロードは有効です。');
}
else
{
System。出力。println('Hashes が一致しません。Webhook ペイロードは改ざんされています。');
}
返品する calculatedHmac;
}