Webhook ガイド
設定 コアAPI アウトバウンド Webhook (X-Webhook-Signature) ライセンスおよびプラットフォーム イベント用。
Pay 支払い Webhook の場合は使用します 販売者への Webhook の支払い。 ミラーリダイレクト署名については、を参照してください。 ミラーSDK.
概要
Webhook を使用すると、LicenseChain アカウントでイベントが発生したときに、
コアAPI (POST /v1/webhooks）。有料販売者イベントの使用
販売者への Webhook の支払い;
ミラーリダイレクトでは、 ミラーSDK サインの流れ。
学べること
セットアップと構成
- Webhook の作成と管理
- Webhook エンドポイントの構成
- イベントサブスクリプションの設定
- Webhook のセキュリティと署名
実装
- Webhook イベントの受信
- Webhook 署名の検証
- Webhook の失敗の処理
- Webhook エンドポイントのテスト
Webhook の作成
1. Webhook エンドポイントを作成する
まず、LicenseChain から POST リクエストを受信できる HTTP エンドポイントをアプリケーションに作成します。
// Express.js Example
app.post('/webhooks/licensechain', async (req, res) => {'{'}
const signature = req.headers['x-webhook-signature'];
const timestamp = req.headers['x-webhook-timestamp'];
const payload = JSON.stringify(req.body);
// Verify signature (see Security section)
if (!verifySignature(payload, signature, timestamp, webhookSecret)) {'{'}
return res.status(401).send('Invalid signature');
{'}'}
// Process webhook event
const event = req.body;
console.log('Received event:', event.type, event.data);
res.status(200).send('OK');
{'}'});
2. Webhook を登録する
LicenseChain API を使用して Webhook エンドポイントを登録します。 URL を指定し、受信するイベントを指定する必要があります。
POST /v1/webhooks
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{'{'}
"url": "https://your-app.com/webhooks/licensechain",
"events": ["license.created", "license.updated", "license.revoked"],
"secret": "optional-custom-secret"
{'}'}
注記： シークレットを指定しない場合は、LicenseChain が自動的にシークレットを生成します。 Webhook 署名を検証するためにこのシークレットが必要になるため、このシークレットは安全に保存してください。
3. 利用可能なイベント
LicenseChain は、次の Webhook イベントをサポートします。
セキュリティと署名の検証
Webhook 署名
すべての Webhook リクエストには、 X-Webhook-Signature ヘッダ。
署名は、Webhook シークレットを使用した生のリクエスト本文の HMAC-SHA256 です。常に次を使用して検証します 定数時間比較 （例えば。 crypto.timingSafeEqual) タイミング攻撃を防ぐため。ヘッダー値は生の 16 進数または sha256= その後に 16 進数が続きます。剥ぎ取る sha256= 16 進バッファを比較する前にプレフィックスを付けて長さが一致するようにします。
// Node.js Example (constant-time, supports sha256= prefix)
const crypto = require('crypto');
function verifySignature(payload, signature, secret) {'{'}
if (!payload || !signature || !secret) return false;
const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
const received = String(signature).startsWith('sha256=') ? String(signature).slice(7) : String(signature);
const a = Buffer.from(expected, 'hex');
const b = Buffer.from(received, 'hex');
if (a.length !== b.length) return false;
return crypto.timingSafeEqual(a, b);
{'}'}
// In your webhook handler (use raw body for payload)
const signature = req.headers['x-webhook-signature'];
const payload = req.rawBody || JSON.stringify(req.body);
if (!verifySignature(payload, signature, webhookSecret)) {'{'}
return res.status(401).send('Invalid signature');
{'}'}
リクエストヘッダー
LicenseChain には、各 Webhook リクエストに次のヘッダーが含まれます。
X-Webhook-Signature
リクエスト本文の HMAC-SHA256 署名
X-Webhook-Timestamp
Webhook が送信されたときの Unix タイムスタンプ
Content-Type
いつも application/json
Webhook イベントの構造
すべての Webhook イベントは一貫した構造に従います。
{'{'}
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "license.created",
"data": {'{'}
"id": "license-id",
"licenseKey": "ABC123...",
"userId": "user-id",
"productId": "product-id",
"status": "active",
"expiresAt": "2024-12-31T23:59:59Z",
"createdAt": "2024-01-01T00:00:00Z"
{'}'},
"timestamp": "2024-01-01T00:00:00Z",
"signature": "hmac-sha256-signature"
{'}'}
Webhook の管理
すべての Webhook をリストする
GET /v1/webhooks?page=1&limit=10 Authorization: Bearer YOUR_API_KEY
Webhook の詳細を取得する
GET /v1/webhooks/:id Authorization: Bearer YOUR_API_KEY
Webhook を更新する
PUT /v1/webhooks/:id
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{'{'}
"url": "https://new-url.com/webhooks",
"events": ["license.created", "license.updated"]
{'}'}
Webhook の削除
DELETE /v1/webhooks/:id Authorization: Bearer YOUR_API_KEY
Webhook のテスト
テスト Webhook を送信する
実際のイベントが発生するのを待たずに、Webhook エンドポイントをテストできます。
POST /v1/webhooks/:id/test Authorization: Bearer YOUR_API_KEY
これにより、サンプル ペイロードを含むテスト イベントが Webhook URL に送信されます。これを使用して、エンドポイントが正しく動作していることを確認します。
Webhook ログの表示
各 Webhook イベントの配信ステータスと応答を確認します。
GET /v1/webhooks/:id/logs?page=1&limit=10 Authorization: Bearer YOUR_API_KEY
ログには、HTTP ステータス コード、応答本文、配信が成功したかどうかが含まれます。
ベストプラクティス
✅ 署名を常に検証する
署名を検証せずに Webhook イベントを処理しないでください。これにより、リクエストが LicenseChain からのものであり、改ざんされていないことが保証されます。
✅ 迅速な対応
Webhook エンドポイントは 5 秒以内に応答する必要があります。長時間実行される操作の場合は、Webhook をすぐに確認して、非同期に処理します。
✅ べき等性を処理する
同じイベントが複数回処理されるのを防ぐには、イベント ID を使用します。処理されたイベント ID を保存し、処理前に確認します。
✅ HTTPS を使用する
転送中のデータが確実に暗号化されるように、Webhook エンドポイントには常に HTTPS を使用してください。
✅ Webhook ログを監視する
Webhook ログを定期的にチェックして、配信の問題を特定して修正します。失敗した配信に対するアラートを設定します。
トラブルシューティング
Webhook がイベントを受信しない
- • Webhook URL がインターネットからアクセスできることを確認します。
- • エンドポイントが 2xx ステータス コードを返すことを確認します。
- • 購読しているイベントが実際に開催されていることを確認する
- • Webhook ログで配信エラーを確認する
署名検証の失敗
- • 正しい Webhook シークレットを使用していることを確認してください
- • 正確なリクエスト本文 (JSON 文字列として) に署名していることを確認します。
- • HMAC-SHA256 アルゴリズムを使用していることを確認します。
- • ヘッダーが正しく読み取られていることを確認します (大文字と小文字が区別されます)。
タイムアウトエラー
- • Webhook ハンドラーを最適化して迅速に応答する
- • 負荷の高い処理をバックグラウンド ジョブに移動する
- • すぐに 200 OK を返し、非同期で処理します。
次のステップ
Webhook について理解したので、次のことができるようになります。