Webhook
このページでは、PocketSign Platform から Webhook を運用する際の判断基準と手順をまとめます。Webhook の概念やエンドポイント仕様は サービスウェブフック、設定項目の意味は ウェブフック設定 を参照してください。
Webhook はサービス詳細画面の「Webhook」タブで管理します。以下はサンプルサービス（sample-service）の例です。
Webhook URL の変更や有効化・無効化は「編集」から行います。リソースイベントを購読する場合は、この画面で対象リソースを追加します。
削除の影響
Webhook を削除すると、次の影響があります。
- 削除は元に戻せません
- 配信中・キューに残っているイベントは失われる場合があります
- 同じエンドポイント URL で再作成しても新しい Webhook となり、サービス側で JWT 検証に使う
iss/subの取り扱いを見直す必要があります
削除前に次を確認してください。
- そのエンドポイントへ配信される KLONEvent を別経路で受ける必要がないこと
- 一時的に配信を止めたいだけであれば、削除ではなく Webhook の無効化で代替できないか
自動無効化からの復旧
KLON は配信に連続して失敗した Webhook を自動的に無効化します。自動無効化の条件は サーキットブレーカー を参照してください。
自動無効化された Webhook を復旧する手順は次のとおりです。
- サービスのバックエンドサーバーが KLONEvent を受信できる状態になっていることを確認します
- エンドポイントが エンドポイント仕様 に従って
2xxを 10 秒以内に返すことを動作確認します（無効状態のままでも テスト送信 が行えます） - PocketSign Platform の Webhook 設定画面で当該 Webhook を再有効化します
- 再有効化後の数件のイベント配信が成功することを確認します
再有効化すると連続失敗回数がリセットされます。エンドポイント側の問題が解消していない状態で再有効化すると、再び自動無効化されます。
テスト送信で疎通を確認する
Webhook 設定を作成すると、「Webhook」タブに「テスト送信」ブロックが表示されます。実際のイベント発生を待たずに、登録済みの URL へテスト用の KLONEvent を 1 件だけ送信できます。エンドポイントを実装した直後の疎通確認や、自動無効化からの復旧確認に利用します。
- 「送信するイベント」で送信するイベントを選びます
- 疎通確認テストイベント (webhook/test): 疎通確認専用のイベント。通常の配信では発生しません。到達性と署名検証だけを確認したい場合に使います
- サービス利用開始 (ダミーデータ) などの既存イベント種別: そのイベント種別のダミーデータを送信します。受信側のイベント分岐まで確認したい場合に使います
- 「テストイベントを送信」を押します
- ボタンの下に表示される結果を確認します
結果表示の読み方
| 表示 | 意味 | 主な確認先 |
|---|---|---|
| テストイベントを送信しました（HTTP 2xx） | エンドポイントが 2xx を応答した | 受信側でイベントを処理できたかをログで確認します |
| エンドポイントがエラーを応答しました（HTTP 4xx / 5xx） | 到達したが 2xx 以外を応答した | パス・HTTP メソッド（POST）・認証設定・アプリケーションのエラーを確認します |
| テストイベントを送信できませんでした | 応答が得られなかった（名前解決・TLS・接続の失敗、タイムアウトなど） | URL の綴り、DNS、証明書、インターネットからの到達性を確認します |
いずれの場合も、送信したイベントの ID が表示されます。この値は KLONEvent の jti クレームと一致するため、受信側のログとの突き合わせに使えます。
送信内容と注意点
- 送信形式・署名は本番のイベント配信と同一で、
events内のイベントデータにtest: trueが付与される点だけが異なります。受信側ではtestを確認し、業務処理を実行しないようにしてください - ダミーイベントの
subscription_id/resource_definition_idは nil UUID（00000000-0000-0000-0000-000000000000）です。実在しない ID のため、これらを使った API 呼び出しではデータを取得できません - Webhook が無効状態（自動無効化を含む）でも送信できます。再有効化する前にエンドポイントの復旧を確認できます
- リトライは行わず 1 回だけ送信します。結果はサーキットブレーカーの連続失敗回数に影響しません
ペイロードの詳細は ウェブフック設定 を参照してください。
イベント種別フィルタの運用
ウェブフック設定でイベント種別を指定すると、指定したイベントのみを受信できます。実運用では次の使い分けが有効です。
- 受信対象を絞って実装規模を小さくしたい場合は、必要なイベント種別だけを指定します
- すべての KLONEvent を受信したい場合は、指定をしません
- イベント種別を後から追加する場合は、サービス側のハンドラが新しい種別を受け取れることを先に確認してから設定を変更してください
指定可能なイベント種別の一覧は KLONEvent 仕様 を参照してください。
関連ページ
- Webhook の全体像は サービスウェブフック
- 設定項目の意味は ウェブフック設定
- エンドポイントの実装要件は エンドポイント仕様
- 受信可能なイベントは KLONEvent 仕様