Webhookの検証

FrictioはWebhookの配信にSvixを使用しています。機密性を担保するため、ペイロードデータのログは送信後に削除されます。受信側では、送られてきたリクエストが本当にFrictioからのものかを署名で検証することを推奨します。検証には、Svix公式ライブラリを使う方法と、自前で署名を計算する方法があります。

1. Svix公式ライブラリによる検証（推奨）

公式ライブラリを使うと、署名とタイムスタンプの検証を一括で行えます。

Python
Node.js
Java
Kotlin

pip install svix

from svix import Webhook, WebhookVerificationError

secret = "your-webhook-secret"
headers = {
    "webhook-id": "msg_p5jXN8AQM9LWM0D4loKWxJek",
    "webhook-timestamp": "1614265330",
    "webhook-signature": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=",
}

wh = Webhook(secret)
try:
    verified_payload = wh.verify(payload, headers)
except WebhookVerificationError:
    raise ValueError("Webhook verification failed!")

npm install svix
# または
yarn add svix

import { Webhook } from "svix";

const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

// これらはすべてサーバーから送信されたものです
const headers = {
  "webhook-id": "msg_p5jXN8AQM9LWM0D4loKWxJek",
  "webhook-timestamp": "1614265330",
  "webhook-signature": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=",
};
const payload = '{"test": 2432232314}';

const wh = new Webhook(secret);
// エラー時は例外、成功時は検証済みのコンテンツを返します
wh.verify(payload, headers);

Gradleの場合、プロジェクトのビルドファイルに以下の依存関係を追加します。

implementation "com.svix:svix:0.x.y"

Mavenの場合、pom.xml に以下の依存関係を追加します。

<dependency>
  <groupId>com.svix</groupId>
  <artifactId>svix</artifactId>
  <version>0.x.y</version>
</dependency>

import com.svix.Webhook;

String secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

// これらはすべてサーバーから送信されたものです
HashMap<String, List<String>> headerMap = new HashMap<String, List<String>>();
headerMap.put("webhook-id", Arrays.asList("msg_p5jXN8AQM9LWM0D4loKWxJek"));
headerMap.put("webhook-timestamp", Arrays.asList("1614265330"));
headerMap.put("webhook-signature", Arrays.asList("v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE="));
HttpHeaders headers = HttpHeaders.of(headerMap, (a, b) -> true);

String payload = "{\"test\": 2432232314}";

Webhook webhook = new Webhook(secret);

webhook.verify(payload, headers);
// 検証失敗時は WebhookVerificationError 例外をスローします

Gradleの場合、プロジェクトのビルドファイルに以下の依存関係を追加します。

implementation "com.svix.kotlin:svix-kotlin:0.x.y"

Mavenの場合、pom.xml に以下の依存関係を追加します。

<dependency>
  <groupId>com.svix.kotlin</groupId>
  <artifactId>svix-kotlin</artifactId>
  <version>0.x.y</version>
</dependency>

import com.svix.kotlin.Webhook

val secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

// これらはすべてサーバーから送信されたものです
val headersMap = mapOf(
    "webhook-id" to listOf("msg_p5jXN8AQM9LWM0D4loKWxJek"),
    "webhook-timestamp" to listOf("1614265330"),
    "webhook-signature" to listOf("v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=")
)
val headers = HttpHeaders.of(headersMap) { _, _ -> true }

val payload = "{\"test\": 2432232314}";

val webhook = Webhook(secret);

webhook.verify(payload, headers)
// 検証失敗時は WebhookVerificationError 例外をスローします

2. 自前での署名検証（Manual Verification）

ヘッダーとシークレットキーを用いて、受け取ったペイロードが正当なものかを自前で検証します。

必要なもの

HTTPヘッダー（webhook-id, webhook-timestamp, webhook-signature）
- webhook-id: Webhookメッセージの一意な識別子。すべてのメッセージ間で一意だが、同じWebhookが再送信された場合（以前の送信が失敗した場合など）は同じ識別子が使用される
- webhook-timestamp: エポック（UNIX時間）からの経過秒数で表されたタイムスタンプ
- webhook-signature: Base64でエンコードされた署名のリスト（スペースで区切られた複数の署名を含む場合がある）
Webhookシークレットキー（Frictio管理画面で発行）
payload（リクエストボディ）

手順

1. 署名対象コンテンツの構築

署名に使用されるコンテンツは、id・timestamp・payloadをピリオド（.）で連結したものです。

const signedContent = `${webhookId}.${webhookTimestamp}.${body}`;

ここで body はリクエストの生（raw）ボディを指します。署名は非常に敏感で、body がわずかにでも変更されると署名は完全に異なるものになります。そのため、署名を検証する前に body を一切変更しないことが重要です。

2. 期待される署名の算出

Webhookの署名にはHMAC（ハッシュベースのメッセージ認証コード）とSHA-256を使用しています。署名の検証を行うには、signedContent を、署名シークレットのBase64部分をキーとして使い、HMAC-SHA256で署名（ハッシュ）します。署名シークレットが whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw の場合、実際の秘密鍵として使うのは whsec_ の後ろの部分（MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw）です。

const crypto = require('crypto');

const signedContent = `${webhookId}.${webhookTimestamp}.${body}`;
const secret = "whsec_5WbX5kEWLlfzsGNjH64I8lOOqUB6e8FH";

// シークレットをbase64デコードする必要があります
const secretBytes = Buffer.from(secret.split('_')[1], "base64");
const signature = crypto
  .createHmac('sha256', secretBytes)
  .update(signedContent)
  .digest('base64');

console.log(signature);

生成した署名は、webhook-signature ヘッダー内に含まれるいずれかの署名と一致している必要があります。 webhook-signature ヘッダーは、スペース区切りで並んだ複数の署名とそのバージョン識別子で構成されています。通常は1つだけですが、複数の署名が含まれる場合もあります。

v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= v1,bm9ldHUjKzFob2VudXRob2VodWUzMjRvdWVvdW9ldQo= v2,MzJsNDk4MzI0K2VvdSMjMTEjQEBAQDEyMzMzMzEyMwo=

署名の検証を行う前に、各署名のバージョンプレフィックス（例: v1,）と区切り文字を取り除いてください。また、署名の比較にはタイミング攻撃（timing attack）を防ぐために、定数時間（constant-time）で文字列を比較する方法の使用が推奨されます。

タイムスタンプの検証

各リクエストの試行時刻を webhook-timestamp ヘッダーに含めて送信します。このタイムスタンプを自身のシステムの現在時刻と比較し、許容範囲内（過去5分以内）にあることを確認してください。これはリプレイ攻撃（replay attack）を防ぐためです。

署名の検証例

以下は、実装が正しく行われているか確認するために使える検証用の例です。なお、この例ではタイムスタンプが古いため、検証に失敗する可能性があることに注意してください。

secret = 'whsec_plJ3nmyCDGBKInavdOK15jsl';
payload = '{"event_type":"ping","data":{"success":true}}';
msg_id = 'msg_loFOjxBNrRLzqYUf';
timestamp = '1731705121';

// 上記から次の署名が生成されます
signature = 'v1,rAvfW3dJ/X/qxhsaXPOyyCGmRKsaKWcsNccKXlIktD0=';

署名の照合: v1, プレフィックスを取り除いた値と、計算した署名（computed_signature）を比較し、一致すればOKです
タイムスタンプの検証: webhook-timestamp が過去5分以内であるかを確認します

Overview

API Reference

Webhook Reference

Resources

1. Svix公式ライブラリによる検証（推奨）

2. 自前での署名検証（Manual Verification）

必要なもの

手順

1. 署名対象コンテンツの構築

2. 期待される署名の算出

タイムスタンプの検証

署名の検証例

参考リンク

​1. Svix公式ライブラリによる検証（推奨）

​2. 自前での署名検証（Manual Verification）

​必要なもの

​手順

​1. 署名対象コンテンツの構築

​2. 期待される署名の算出

​タイムスタンプの検証

​署名の検証例

​参考リンク

1. Svix公式ライブラリによる検証（推奨）

2. 自前での署名検証（Manual Verification）

必要なもの

手順

1. 署名対象コンテンツの構築

2. 期待される署名の算出

タイムスタンプの検証

署名の検証例

参考リンク