Skip to Content
新しいバージョン 12 を公開しました 🎉

Webhook Data Center

Webhook を使うと、Babel Licensing Service で特定のイベントが発生したときに、外部アプリケーションがリアルタイムで通知を受け取れます。既存のシステムとの接続、ワークフローの自動化、データの同期に使用できます。

Webhook

Webhook へのアクセス

Webhook には、Babel Licensing Service のメインナビゲーションメニューからアクセスできます。左のサイドバーにある「Webhooks」メニュー項目をクリックすると、Webhook の管理インターフェイスが開きます。

Webhook の管理

Webhook の表示

Webhook ページには、設定済みのすべての Webhook のサブスクリプションとその詳細が、表で表示されます。

  • Name:Webhook のわかりやすい名前。
  • URL:イベント通知の送信先となるエンドポイント。URL は、http または https を使用している場合にのみ、クリックできるリンクとして表示されます。
  • Event:Webhook がサブスクライブしているイベントの種類。
  • Owner User:Webhook を作成したユーザー。
  • Sent At:最後にイベントが配信された日時。
  • Next Retry:次に配信が試行される日時(該当する場合)。
  • Status:Webhook の現在の状態(OK、Error など)。

新しい Webhook の追加

新しい Webhook のフォームを開く

Webhook ページの右上隅にある「+ ADD」ボタンをクリックします。

必要な情報を入力する

  • Name:Webhook のわかりやすい名前を入力します。
  • URL:通知の送信先となるエンドポイントの URL を指定します。
  • Event:サブスクライブするイベントの種類を選択します。
  • Secret:要求の検証に使用するシークレットキーを生成または入力します。

Webhook を保存する

「Save」をクリックして、Webhook のサブスクリプションを作成します。

Webhook の編集

Webhook を見つける

一覧で Webhook を見つけます。

エディターを開く

行の編集アイコン(鉛筆)をクリックします。

詳細を変更する

Webhook の詳細を変更します。

変更を保存する

「Save」をクリックして、Webhook のサブスクリプションを更新します。

Webhook の削除

Webhook のサブスクリプションを見つける

一覧で Webhook のサブスクリプションを見つけます。

削除する

行の削除アイコン(ごみ箱)をクリックします。

削除を確定する

確認を求められたら、削除を確定します。

Webhook のテスト

Webhook のサブスクリプションを見つける

一覧で Webhook のサブスクリプションを見つけます。

テストイベントを送信する

更新アイコンをクリックして、テストイベントを送信します。

配信結果を表示する

Webhook イベントの詳細で、配信結果を確認します。

テストイベントは、同じヘッダーと署名検証を含め、実際のイベントと同じ配信の仕組みで処理されるため、エンドポイントが Webhook のペイロードを正しく処理できることを検証できます。

Webhook イベントの詳細

Webhook がトリガーされると、展開されたビューに配信の詳細が表示されます。

  • Timestamp:イベントが発生した日時。
  • Event Type:イベントの種類(例:license.created)。
  • Status:配信の状態(OK、Failed)。
  • Response:エンドポイントから受信した応答。
  • Error:エラーメッセージ(配信に失敗した場合)。
  • Retry Count:配信の試行回数。
  • Next Retry:次の再試行が行われる日時(該当する場合)。

サポートされるイベント

Babel Licensing Service は、次の Webhook イベントをサポートしています。

ライセンス

  • license.created:新しいライセンスが作成されたときにトリガーされます。
  • license.updated:既存のライセンスが更新されたときにトリガーされます。
  • license.deleted:ライセンスが削除されたときにトリガーされます。
  • license.expiring:ライセンスの期限がまもなく切れるときにトリガーされます。
  • license.expired:ライセンスの期限が切れたときにトリガーされます。
  • license.revoked:ライセンスが失効したときにトリガーされます。
  • license.supportexpiring:ライセンスの保守期限がまもなく切れるときにトリガーされます。
  • license.supportexpired:ライセンスの保守期限が切れたときにトリガーされます。
  • license.activated:ライセンスがアクティベートされたときにトリガーされます。
  • license.deactivated:ライセンスのアクティベーションが解除されたときにトリガーされます。
  • license.requested:ライセンスが要求されたときにトリガーされます。
  • license.released:ライセンスが解放されたときにトリガーされます。

注文

  • order.created:新しい注文が作成されたときにトリガーされます。
  • order.updated:既存の注文が更新されたときにトリガーされます。
  • order.deleted:注文が削除されたときにトリガーされます。

レポート

report.created:新しいレポートが作成されたときにトリガーされます。

Webhook ペイロードのリファレンス

このセクションでは、イベントの種類ごとに、Webhook イベントのペイロードの構造と内容を詳しく説明します。

ライセンスイベントのペイロード

ライセンスイベント(license.created など)を処理する場合、ペイロードには次のフィールドが含まれます。

{ "id": 101, "licenseId": "LIC-0001", "userKey": "XJK-SHJD-GE5E", "licensee": "Acme Corp", "licensingMode": 1, "issueDate": "2025-03-16T00:00:00Z", "supportExpireDate": "2026-03-16T00:00:00Z", "expireDate": "2025-12-31T23:59:59Z", "customerId": 501, "orderId": 302, "templateId": 10, "revoked": false, "trace": false, "eventType": "license.created", "timestamp": "2025-03-16T12:00:00Z" }
フィールド型説明
id整数ライセンスの一意のデータベース識別子。API での参照と内部の追跡に使用されます。
licenseId文字列顧客とのやり取りやドキュメントで使用される、人が読めるライセンス識別子(例:「LIC-0001」)。
userKey文字列ライセンス対象のソフトウェアをアクティベートするために、エンドユーザーが入力するアクティベーションキー。
licensee文字列ライセンスの発行先である個人または組織の名前。
licensingMode整数適用されるライセンスモードの種類(例:「0: File」、「1: Activation」、「2: Floating」)。
issueDateISO 8601 日時ライセンスが最初に発行された日時。
supportExpireDateISO 8601 日時このライセンスのテクニカルサポートが終了する日時。
expireDateISO 8601 日時ライセンス自体の期限が切れて無効になる日時。
customerId整数このライセンスを所有する顧客への参照。システム内の顧客レコードに対応します。
orderId整数このライセンスが購入された注文への参照。
templateId整数このライセンスの生成に使用されたライセンステンプレートの ID。ライセンスの機能と制限を決定します。
revokedブール値ライセンスが管理上無効にされた(true)か、有効なままである(false)かを示します。
traceブール値ライセンスでトレースが有効になっているかどうかを示します。
eventType文字列この Webhook をトリガーしたイベントの種類を示します(例:「license.created」、「license.updated」)。
timestampISO 8601 日時イベントが発生し、Webhook が送信された正確な時刻。

注文イベントのペイロード

注文に関連するイベント(order.created など)の場合、Webhook のペイロードには次のフィールドが含まれます。

{ "id": 202, "orderNumber": "ORD-12345", "customerId": 501, "createdAt": "2025-03-16T12:00:00Z", "status": "completed", "eventType": "order.created", "timestamp": "2025-03-16T12:05:00Z" }
フィールド型説明
id整数注文の一意のデータベース識別子。API を呼び出して注文の詳細を取得するときに、この ID を使用します。
orderNumber文字列顧客とのやり取りや財務記録で使用される、人が読める注文参照番号。
customerId整数注文を行った顧客の一意の識別子。顧客レコードを参照します。
createdAtISO 8601 日時注文がシステムに最初に作成された日時。
status文字列注文の現在の処理状態。取りうる値には、「pending」、「processing」、「completed」、「cancelled」、「refunded」があります。
eventType文字列この Webhook をトリガーした注文イベントを示します(例:「order.created」、「order.updated」、「order.deleted」)。
timestampISO 8601 日時イベントが発生し、Webhook が送信された正確な時刻。

レポートイベントのペイロード

レポートに関連するイベント(report.created など)の場合、Webhook のペイロードには次のフィールドが含まれます。

{ "id": 303, "name": "Monthly Report", "date": "2025-03-15T00:00:00Z", "eventType": "report.created", "timestamp": "2025-03-16T12:10:00Z" }
フィールド型説明
id整数レポートの一意のデータベース識別子。API でレポート全体を取得するときに、この ID を使用します。
name文字列システムで定義された、レポートのわかりやすいタイトル。
dateISO 8601 日時レポートの内容に関連付けられた日付(通常はレポート対象期間の終了日)。
eventType文字列この Webhook をトリガーしたレポートイベントを示します(現在は「report.created」のみ)。
timestampISO 8601 日時イベントが発生し、Webhook が送信された正確な時刻。

Webhook の配信と再試行のロジック

Babel Licensing Service は、継続的に動作するバックグラウンドサービスで Webhook を処理します。

  • サービスは、30 秒ごとに新しい Webhook イベントを確認します。
  • Webhook は、一度に最大 50 件のイベントのバッチで処理されます。
  • システムは、保留中の(新しい)イベントと、以前に失敗して再試行が予定されているイベントの両方を処理します。
  • 各 Webhook の配信には、次の標準ヘッダーが含まれます。
    • User-Agent:Babel Licensing Service を識別します。
    • X-Babel-Webhook-Id:Webhook の配信の一意の識別子。
    • X-Babel-Event:配信されるイベントの種類。
    • X-Babel-Timestamp:イベントが送信された日時。
    • X-Babel-Signature:HMAC-SHA256 署名(シークレットが設定されている場合)。

再試行の仕組み

Webhook の配信に失敗した場合の動作は、次のとおりです。

  • システムは、5 分後の再試行を自動的に予定します。
  • Webhook ごとに、最大再試行回数を設定できます。
  • 失敗したイベントは、配信に成功するか最大再試行回数に達するまで、システムに残ります。
  • Webhook のインターフェイスには、失敗した配信について、次に予定されている再試行の時刻が表示されます。
  • 失敗した配信ごとに、トラブルシューティングのためのエラーメッセージまたは HTTP ステータスコードが保存されます。

Webhook の状態

システム内の Webhook は、次の状態になります。

  • OK:イベントは正常に配信されました。
  • Failed:イベントの配信に失敗し、最大再試行回数を超えました。
  • Pending:イベントは処理を待っています。
  • Scheduled:イベントの配信に失敗し、再試行が予定されています。

Webhook の保護

すべての Webhook 要求には、X-Babel-Signature ヘッダーに署名が含まれます。この署名は、Webhook のシークレットキーと要求本文を入力として、HMAC-SHA256 で生成されます。

Webhook を検証するには、次の手順に従います。

署名を取得する

X-Babel-Signature ヘッダーから署名を取得します。

期待される署名を計算する

シークレットキーと未加工の要求本文を使って、HMAC-SHA256 署名を計算します。

署名を比較する

計算した署名を、ヘッダーの署名と比較します。

一致した場合にのみ処理する

署名が一致した場合にのみ、Webhook を処理します。

検証コードの例(C#):

private bool VerifyWebhookSignature(string payload, string signatureHeader, string secret) { using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret)); var computedHash = hmac.ComputeHash(Encoding.UTF8.GetBytes(payload)); var computedSignature = Convert.ToBase64String(computedHash); return signatureHeader == computedSignature; }

Webhook レシーバーの実装

次に、Webhook の署名を正しく検証する Webhook レシーバーを ASP.NET Core で実装する、完全な例を示します。

// WebhookValidator.cs using System; using System.Security.Cryptography; using System.Text; namespace YourProject.Utilities { public static class WebhookValidator { /// <summary> /// Validates the webhook payload against the provided signature using HMAC-SHA256. /// </summary> /// <param name="payload">The raw JSON payload.</param> /// <param name="secret">The shared secret.</param> /// <param name="signature">The signature from the incoming request header.</param> /// <returns>True if the signature is valid; otherwise, false.</returns> public static bool ValidateSignature(string payload, string secret, string signature) { using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret)); var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(payload)); var computedSignature = BitConverter.ToString(hash).Replace("-", "").ToLowerInvariant(); return string.Equals(computedSignature, signature, StringComparison.OrdinalIgnoreCase); } } } // WebhookController.cs using Microsoft.AspNetCore.Mvc; using Microsoft.Extensions.Logging; using System.IO; using System.Threading.Tasks; using YourProject.Utilities; namespace YourProject.Controllers { [ApiController] [Route("api/webhook")] public class WebhookController : ControllerBase { private readonly ILogger<WebhookController> _logger; // Ideally, the secret comes from configuration private readonly string _webhookSecret = "your-webhook-secret"; public WebhookController(ILogger<WebhookController> logger) { _logger = logger; } [HttpPost] public async Task<IActionResult> ReceiveWebhook() { // Read the payload from the request body var payload = await new StreamReader(Request.Body).ReadToEndAsync(); // Retrieve the signature from the request headers if (!Request.Headers.TryGetValue("X-Babel-Signature", out var incomingSignature)) { _logger.LogWarning("Missing X-Babel-Signature header"); return Unauthorized("Signature header missing"); } // Validate the signature if (!WebhookValidator.ValidateSignature(payload, _webhookSecret, incomingSignature)) { _logger.LogWarning("Invalid webhook signature"); return Unauthorized("Invalid signature"); } // Process the webhook payload _logger.LogInformation("Webhook payload validated and processed"); // TODO: Deserialize and process the payload as needed return Ok(); } } }

Webhook を受信するためのベストプラクティス

Webhook レシーバーを実装するときは、次の点に注意してください。

  1. 常に署名を検証する:提供されている署名検証コードを使って、各 Webhook の信頼性を検証します。
  2. Webhook のシークレットを安全に保管する:例のようにハードコードせず、安全な構成システムを使用します。
  3. すばやく応答する:署名を検証したら、すぐに 200 OK の応答を返します。
  4. 非同期で処理する:検証して応答を返した後に、バックグラウンドスレッドまたはキューで Webhook を処理します。
  5. べき等性を実装する:Webhook が複数回配信された場合に重複して処理しないよう、イベント ID を使用します。
  6. すべての Webhook イベントをログに記録する:デバッグと監査のために、受信したすべての Webhook の記録を保持します。

Webhook イベントの処理

さまざまな種類のイベントの処理

Webhook レシーバーは、イベントの種類に応じて適切に処理できるように設計する必要があります。次の例は、署名を検証した後に、さまざまな Webhook イベントを処理する方法を示しています。

// Example of webhook event processing private async Task ProcessWebhookEvent(string payload, string eventType) { switch (eventType) { case "license.created": await ProcessNewLicense(payload); break; case "license.expired": await ProcessExpiredLicense(payload); break; case "order.created": await ProcessNewOrder(payload); break; // Handle other event types default: _logger.LogWarning($"Unhandled webhook event type: {eventType}"); break; } } // Example deserialization and processing private async Task ProcessNewLicense(string payload) { try { // Deserialize the payload var licenseEvent = JsonSerializer.Deserialize<LicenseCreatedEvent>(payload); // Process the license _logger.LogInformation($"Processing new license: {licenseEvent.LicenseId}"); // Example: Store in your database, notify users, etc. await _licenseService.SyncLicenseAsync(licenseEvent.Id); } catch (Exception ex) { _logger.LogError(ex, "Error processing license.created webhook"); } }

トラブルシューティング

よくある問題

  • Webhook がイベントを受信しない:ダッシュボードで Webhook の状態を確認し、そのイベントの種類をサブスクライブしていることを確かめます。
  • 認証の失敗:署名検証コードが正しいこと、Webhook に設定したものと同じシークレットを使用していることを確認します。
  • タイムアウト:エンドポイントが妥当な時間内に応答するようにします(システムは、応答を待ってから成功と判定します)。
  • 無効な URL:Webhook の URL がインターネットからアクセスでき、HTTP 2xx のステータスコードを返すことを確認します。
  • カスタムヘッダーが適用されない:Webhook の構成で、カスタムヘッダーの形式を見直します。
  • Webhook が失敗と表示される:Webhook の詳細でエラーメッセージを確認し、発生した HTTP ステータスコードまたは例外を特定します。

Webhook の履歴の表示

Webhook ごとに、配信履歴の全体を表示できます。

  1. メインの一覧で Webhook をクリックして、詳細を展開します。
  2. 履歴セクションには、すべての配信の試行が、タイムスタンプ、イベントの種類、状態、エラーメッセージとともに表示されます。
  3. この情報を使って、配信の問題を診断したり、配信の成功を確認したりします。
Last updated on