このチュートリアルでは、HTTPSタイプのWebhookエンドポイントの設定、テスト、および検証方法を説明します。
1. エンドポイントの登録
エンドポイントは、イベント通知を正しく処理できる有効な SSL 証明書を持つ HTTPS アドレスである必要があります。
ペイロードには、Webhookイベントのデータを含むJSONオブジェクトが含まれます。
各ペイロードの内容と構造は、サブスクライブしたトピックによって異なります。詳細については、REST APIリソースを参照してください。
2. Webhookトピックの購読
RESTでWebhookリソースにPOSTリクエストを送信します。
例えば、次のリクエストは、plans/createトピックをサブスクライブします。
{
"address": "https://12345.ngrok.io/sub/plans/create",
"topic": "plans/create"
}
3. Webhookのテスト
担当営業に対象トピックと共にご連絡下さい。
現在テスト用の仕組みを準備中です。
4. Webhookを受け取る
エンドポイントを登録すると、protegerはそのイベントが発生するたびに、指定されたURLに HTTP POST リクエストを送信します。HTTP POST リクエストのパラメータには、リクエストをトリガーしたイベントに関連する JSONデータが含まれます。
サーバーが有効な SSL 証明書を使用して HTTPS をサポートするように正しく構成されていることを確認してください。
5. Webhookを認証
Webhookにレスポンスする前に、Webhook が protegerから送られたものであることを認証する必要があります。デジタル署名を検証することで、webhookを認証することができます。
各 Webhook リクエストは base64 エンコードされた X-Proteger-Signature ヘッダーを含み、これはリクエストで送られたペイロードと共に、Webhookシークレットを使って生成されます。
Webhookシークレット
Webhookシークレットは管理画面の「設定」→「Webhook」から確認する事ができます。
例）
sha256アルゴリズムに従って、HMACダイジェストを算出します。
算出された値を X-Proteger-Signatureヘッダーの値と比較します。
package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"errors"
"net/http"
)
func VerifyWebhookRequest(payload []byte, header http.Header, webhookSecret string) error {
hash := hmac.New(sha256.New, []byte(webhookSecret))
hash.Write(payload)
signature := hex.EncodeToString(hash.Sum(nil))
signatureHeader := header.Get("X-Proteger-Signature")
if signature != signatureHeader {
return errors.New("unauthorized")
}
return nil
}
6. Webhookへレスポンス
Webhook は、200 OK レスポンスを送信することで、データを受信したことを確認します。3XX HTTP リダイレクトコードを含む、200以外のレスポンスは、webhookの配信の失敗とみなします。
再送
protegerはwebhookに5秒間のタイムアウトを実装しています。
protegerはwebhookへの各リクエストに対して、5秒間の応答待ちをします。応答がない場合、またはエラーが返された場合、protegerは数秒〜数分の間に再試行します。
タイムアウトやエラーを回避するために、処理は非同期で行う事を検討してください。
設定例
proteger内で保証プランが作成されたイベントを受け取り基幹システムに連携する例です。