Webhookは、protegerのデータと同期すること、または特定のイベントが発生した後にアクションを実行することを可能にします。
Webhookは、protegerのデータの変更を検知するパフォーマンスの高い方法です。
例えば、protegerのplan（保証プラン）が作成されたり変更されたりすると、Webhookはあなたのシステムに通知することができます。そして、イベントが発生したときに、システムはアクションを実行することができます。
このガイドでは、アプリに Webhook を設定する方法と、Webhook の仕組みを紹介します。
トピック
Webhook データはトピックごとに分割されています。サポートされている Webhook トピックの完全なリストについては、REST API リファレンスを参照してください。
ユースケース
Webhookの使用例としては、以下のようなものがあります。
- plan（保証プラン）が作成された時にシステムのマスタと同期する
- plan（保証プラン）が変更された時にシステムのマスタを変更する
- plan（保証プラン）が削除された時にシステムのマスタを削除する
Webhookの概念
このガイドの内容を理解するのに役立つように、以下の定義で Webhook の概念を説明します。
Webhook
単一のイベントメッセージ。protegerは、アプリの Webhook サブスクリプションエンドポイントに Webhook を送信します。Webhook は、ボディに JSONペイロード、ヘッダにメタデータを含みます。
Webhookトピック
イベントのクラス。トピックは、Webhook イベントがいつ作成されるか、また Webhook ペイロードに何が含まれるかを制御します。例えば、plans/createイベントは、plan(保証プラン)が作成されるたびに送信され、ペイロードとして新しいplanが含まれます。
Webhook サブスクリプション
REST APIを使用して作成する永続化されたデータオブジェクトで、以下の2つを定義します。
- 受信したいトピック（イベントのクラス）
- Webhookサブスクリプションエンドポイント、protegerが指定されたトピックのWebhook（イベントメッセージ）を送信する先
Webhookヘッダー
ペイロードに加えて、各Webhookメッセージは、追加のコンテキストを含む様々なヘッダを持ちます。
例えば、plans/create Webhook は以下のヘッダを含みます:
X-Proteger-Topic: `plans/create`
X-Proteger-Signature: `XWmrwMey6OsLMeiZKwP4FppHH3cmAiiJJAweH5Jo4bM=`
X-Proteger-Store-Id: `5e908e73-83e6-210f-1f5e-3afa37db5321`
X-Proteger-Request-Id: `b54557e4-bdd9-4b37-8a5f-bf7d70bcd043`
以下のヘッダーフィールドが使用されます:
| Field | Use |
|---|---|
| X-Proteger-Signature | base64 エンコードされた署名キー |
| X-Proteger-Store-Id | storeの一意なid |
制限
- 同じリソースに対する異なるトピック間では、順番は保証されません。例えば、plans/update webhook が plans/create webhook の前に配信される可能性があります。
- webhooks API は、webhook イベントを「少なくとも一度」配信します。これは、エンドポイントが同じ webhook イベントを複数回受信する可能性があることを意味します。
- Webhook の配信は常に保証されているわけではありません。そのため、protegerから定期的にデータを取得するために、リコンシリエーションジョブの実装を検討する必要があります。
トラブルシューティング
Webhookが配信のレスポンスで200以外のステータスコードを受け取ると、protegerは数秒〜数分以内に再度同じWebhookイベントを配信します。
配信は1度のみ繰り返されます。
エラー内容はヘッダーに含まれるX-Proteger-Request-Idをご用意の上お問い合わせください。