プレビュー版
PocketSign Link v2 は現在プレビュー版です。正式提供までに仕様が変更される可能性があります。
Webhook
このページでは、PocketSign Platform から Webhook を運用する際の判断基準と手順をまとめます。Webhook の概念やエンドポイント仕様は サービスウェブフック、設定項目の意味は ウェブフック設定 を参照してください。
削除の影響
Webhook を削除すると、次の影響があります。
- 削除は元に戻せません
- 配信中・キューに残っているイベントは失われる場合があります
- 同じエンドポイント URL で再作成しても新しい Webhook となり、サービス側で JWT 検証に使う
iss/subの取り扱いを見直す必要があります
削除前に次を確認してください。
- そのエンドポイントへ配信される KLONEvent を別経路で受ける必要がないこと
- 一時的に配信を止めたいだけであれば、削除ではなく Webhook の無効化で代替できないか
自動無効化からの復旧
KLON は配信に連続して失敗した Webhook を自動的に無効化します。自動無効化の条件は サーキットブレーカー を参照してください。
自動無効化された Webhook を復旧する手順は次のとおりです。
- サービスのバックエンドサーバーが KLONEvent を受信できる状態になっていることを確認します
- エンドポイントが エンドポイント仕様 に従って
2xxを 10 秒以内に返すことを動作確認します - PocketSign Platform の Webhook 設定画面で当該 Webhook を再有効化します
- 再有効化後の数件のイベント配信が成功することを確認します
再有効化すると連続失敗回数がリセットされます。エンドポイント側の問題が解消していない状態で再有効化すると、再び自動無効化されます。
イベント種別フィルタの運用
ウェブフック設定でイベント種別を指定すると、指定したイベントのみを受信できます。実運用では次の使い分けが有効です。
- 受信対象を絞って実装規模を小さくしたい場合は、必要なイベント種別だけを指定します
- すべての KLONEvent を受信したい場合は、指定をしません
- イベント種別を後から追加する場合は、サービス側のハンドラが新しい種別を受け取れることを先に確認してから設定を変更してください
指定可能なイベント種別の一覧は KLONEvent 仕様 を参照してください。
関連ページ
- Webhook の全体像は サービスウェブフック
- 設定項目の意味は ウェブフック設定
- エンドポイントの実装要件は エンドポイント仕様
- 受信可能なイベントは KLONEvent 仕様