Webhookのセキュリティ

Webhookのセキュリティ

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

Zoho Sign では、Webhook のセキュリティを確保するために HMAC-SHA 256（SHA 256 を用いたハッシュベースメッセージ認証コード）を使用するオプションを提供しています。これは Webhook の真正性と完全性を保証するための業界標準のハッシュ方式です。Webhook を HMAC で保護すると、次の点を検証できます。
  1. Webhook リクエストが Zoho Sign から送信されたものかどうか（シークレットキーは Zoho Sign と受信アプリケーションのみが知っている必要があります）。
  2. 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 署名の検証

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


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

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