ウェブフック設定

サービスウェブフックは PocketSign Platform から設定します。ウェブフックはサービスごとに 1 つ設定できます。

設定画面はサービス詳細の「Webhook」タブにあります。Webhook URL、有効状態、受信イベント、リソースイベント購読設定を同じ画面で確認できます。

設定項目

項目	必須	説明
URL	はい	KLONEvent の送信先エンドポイント。HTTPS である必要があります
イベント種別	いいえ	受信するイベントの種別。未指定の場合はすべてのイベントを受信します
有効 / 無効	はい	ウェブフックの有効状態

イベント種別のフィルタリング

ウェブフックに受信するイベント種別を指定することで、必要なイベントのみを受信できます。

• イベント種別を指定しない場合: すべてのイベントを受信します
• イベント種別を指定した場合: 指定したイベントのみ受信します

指定可能なイベント種別の一覧は KLONEvent 仕様を参照してください。

テスト送信

登録済みの Webhook URL へ、実際のイベント発生を待たずにテスト用の KLONEvent を送信できます。エンドポイントの疎通確認や、受信側の署名検証・イベント分岐の実装確認に利用します。

操作手順は Webhook（PocketSign Platform） を参照してください。

送信できるイベント

種類	イベントキー	用途
疎通確認テストイベント	https://id.klon.you/events/v1/webhook/test	到達性と署名検証の確認。通常のイベント配信では発生せず、イベント種別のフィルタリングや購読設定の対象にもなりません
既存イベント種別のダミーイベント	KLONEvent 仕様 の各イベントキー	受信側のイベント分岐まで含めた確認

ペイロード

送信されるリクエストは、POST / Content-Type: application/klonevent+jwt / 本番と同じ鍵での署名、および iss iat aud jti toe events の構成が通常の配信と同一です。テスト送信では、events 内のイベントデータに test マーカーが付与される点だけが異なります。

疎通確認テストイベントの例:

{
  "iss": "https://id.mock.klon.you",
  "iat": 1752204930,
  "aud": "6e205c39-a73b-4a5d-b2cf-1d4f0e8b0a60",
  "jti": "0e30e0e1-8a6e-4d7c-8257-7b1f8df6d6c1",
  "toe": 1752204930,
  "events": {
    "https://id.klon.you/events/v1/webhook/test": {
      "service_id": "6e205c39-a73b-4a5d-b2cf-1d4f0e8b0a60",
      "test": true
    }
  }
}

ダミーイベントの例（service/subscribed を選んだ場合）:

{
  "events": {
    "https://id.klon.you/events/v1/service/subscribed": {
      "subscription_id": "00000000-0000-0000-0000-000000000000",
      "service_id": "6e205c39-a73b-4a5d-b2cf-1d4f0e8b0a60",
      "test": true
    }
  }
}

ダミーイベントの subscription_id や resource_definition_id には nil UUID（00000000-0000-0000-0000-000000000000）が入ります。service_id は対象サービスの実際の ID です。実在しない ID のため、これらを使って API を呼び出してもデータは取得できません。

注意

test が true のイベントは動作確認用であり、実際にイベントが発生したことを意味しません。受信側では test マーカーを確認し、業務処理（データ更新や通知の送信など）を実行しないようにしてください。

テスト送信の性質

• Webhook が無効状態（サーキットブレーカー による自動無効化を含む）でも送信できます。再有効化する前の復旧確認に利用できます
• リトライは行わず 1 回だけ送信します。結果はサーキットブレーカーの連続失敗回数に影響しません
• Webhook 設定が未作成のサービスでは利用できません。先に URL を登録してください
• イベント種別のフィルタリングやリソースイベント購読設定にかかわらず、選択したイベントがそのまま送信されます

自動無効化

連続して配信に失敗した場合、サーキットブレーカーによりウェブフックが自動的に無効化されることがあります。詳細はエンドポイント仕様を参照してください。

自動無効化されたウェブフックは、PocketSign Platform から手動で再有効化してください。再有効化すると連続失敗回数がリセットされます。無効状態のままでもテスト送信は行えるため、再有効化の前に テスト送信 でエンドポイントの復旧を確認できます。

関連ページ

• エンドポイントの実装要件は エンドポイント仕様
• 受信可能なイベントは KLONEvent 仕様