エンドポイント仕様

ポケットサインは各種イベントの発生時に、事前に登録されたサービスのエンドポイントへ HTTP リクエストを送信します。このリクエストにより、サービスのバックエンドサーバーは KLONEvent を受け取ります。

リクエスト

項目	内容
送信先エンドポイント	`https://{事前に登録されたポケットサインサーバーからアクセス可能なアドレス}`
HTTP メソッド	`POST`
Content-Type	`application/klonevent+jwt`
リクエストボディ	`klonevent+jwt` 形式の JWT（詳細は KLONEvent 仕様）

サービスはバックエンドサーバーにこのリクエストを受け取るエンドポイントを実装する必要があります。

:::danger 注意サービスのバックエンドサーバーは、JWT の署名を検証することで、このエンドポイントに送信されたリクエストが真にポケットサインから送信されたものかを確認する必要があります。

検証を怠ると、ポケットサインとは全く関係のない第三者から、実際には発生していない架空のイベント通知を受け取り処理してしまう危険性があります。 :::

IdP の JWKS エンドポイントから公開鍵を取得します。

環境	JWKS エンドポイント
ポケットサイン開発環境	`https://id.mock.klon.you/api/oidc/v1/jwks`
テスト環境	`https://id.test.klon.you/api/oidc/v1/jwks`
本番環境	`https://id.klon.you/api/oidc/v1/jwks`

これらのエンドポイントは、RFC 7517 の JWK Set Format で公開鍵を返します。

サービスのバックエンドサーバーは、KLONEvent を正常に受け取った場合、204 No Content またはレスポンスボディが空の 200 OK のレスポンスを返却してください。

また、サービスのバックエンドサーバーはレスポンスを10 秒以内に返却する必要があります。10 秒以内に返却されなかった場合は、ポケットサインはリクエストをタイムアウトとして切断します。

200 番台以外のステータスコードが返却された、またはリクエストがタイムアウトした場合、ポケットサインは通知の送信をリトライします。最大 5 回までリトライを行い、リトライまでの時間間隔は指数バックオフアルゴリズムによって増加します。

連続して配信に失敗した場合、ウェブフックは自動的に無効化されます。

条件	値
連続失敗回数	5 回以上
最初の失敗からの経過時間	5 分以上

上記の両方の条件を満たした場合にサーキットブレーカーが発動し、ウェブフックが自動的に無効化されます。無効化されたウェブフックは PocketSign Platform から手動で再有効化する必要があります。