Webhook エンドポイントで Tokenz のイベントを受信する
WebhookでTokenzアカウントのイベントを受信し、必要な処理を自動で実行します。
金額フォーマット: Webhook ペイロード内の金額値(amount フィールドなど)は各通貨の最小単位で表現されます。通貨ごとの正確なエンコーディングについては、サポートされている通貨を参照してください。
Webhook を使用する理由
Tokenz Checkoutと連携するには、アカウントで発生したイベントを受信し、バックエンドで必要な処理を実行します。
Webhookエンドポイントを登録すると、アカウントでイベントが発生した際にTokenzがそのデータを送信します。イベントオブジェクトは、HTTPS経由でJSONとしてアプリケーションに届きます。
Checkout の結果通知を常に受け取れるよう、リダイレクト処理に加えて Webhook を実装することを強くお勧めします。
イベントオブジェクト
イベントが発生すると、Tokenz は新しいイベントオブジェクトを生成します。 1つの API リクエストで複数のイベントが作成される場合もあります。
Tokenz アカウントに Webhook エンドポイントを登録すると、Tokenz はイベントオブジェクトを登録された Webhook エンドポイントに POST リクエストの一部として自動的に送信できるようになります。 Webhook エンドポイントがイベントを受信すると、アプリはバックエンドアクション (order.succeeded イベントを受信したらお客様に購入商品のダウンロードリンクを送るなど) を実行できます。
Webhookで届くイベントオブジェクトには、関連するオブジェクトのスナップショットとイベントのメタデータが含まれます。
イベントペイロードの例
以下は、注文が成功した場合に送信されるイベントの例です。
{
"id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
"object": "order.succeeded",
"createdAt": "2025-09-24T03:22:20.297Z",
"test": true,
"eventData": {
"type": "order",
"version": "v3",
"data": {
"order": {
"id": "order_1D5xA9BnKfv_t",
"object": "order",
"status": "succeeded",
"amount": {
"amount": 3700,
"currency": "JPY"
},
"items": [
{
"id": "item_1D6F8mR5TnK_t",
"detail": {
"product": {
"price": {
"amount": 1200,
"currency": "JPY"
},
"quantity": 3,
"label": "ひとにぎりのエメラルド",
"description": "80+8",
"images": [
"https://images.ctfassets.net/z82qbo7cv7ia/1dWPbk5Qx2M1Qikj6Knyuc/e37b2c26829c0d30793a348ae3adb3b0/fake-pass.webp"
]
}
}
},
{
"id": "item_1xejV7puGeK_t",
"detail": {
"product": {
"price": {
"amount": 100,
"currency": "JPY"
},
"quantity": 1,
"label": "Diamond",
"description": "",
"images": [],
"sku": "sku_103843dfjhdfgiu",
"taxCategory": "VIRTUAL_CURRENCY"
}
}
}
],
"description": "Game items purchase",
"externalOrderId": "ORDER_2024_001",
"recipientId": "user_42931",
"metadata": { "cartId": "cart_8812" },
"test": true,
"expiresAt": "2024-12-31T23:59:59Z",
"createdAt": "2024-01-15T10:00:00Z",
"updatedAt": "2024-01-15T10:05:30Z"
}
}
}
}
ライブモードとテストモード
1つのエンドポイントをライブモードとテストモードの両方に使用している場合、ライブモードとテストモード両方のイベント配信リクエストをエンドポイントで受け取る場合があります。 テストフラグでオブジェクトがライブモードまたはテストモードのどちらに存在するのか確認し、正しいイベントの処理を判断してください。
バージョン
version はAPIのバージョンを表し、eventData.data 内のデータ構造を決めます。上の例では eventData.data.order に注文が入ります。
イベントのタイプ
| タイプ | 説明 |
|---|---|
order.created | 新しい注文が Checkout Session の作成 エンドポイントから作成されました。 |
order.succeeded | 注文の支払いが完了しました。購入されたアイテムを付与できます。 |
order.expired | 注文の有効期限が切れました。 |
order.canceled | 注文がキャンセルされました。 |
order.failed | 注文の支払いが失敗しました。 |
refund.created | 返金リクエストが作成されました。 |
refund.failed | 返金が失敗しました。 |
dispute.created | 異議申し立てが作成されました。 |
dispute.closed | 異議申し立てが終了しました。 |
redemption.completed | ギフトコードの利用、または無料アイテムの受け取りが完了しました。kind で種類を識別します(source は非推奨)。無料アイテムでは code は省略されます。 |
user.validationはこの一覧にありません。これはイベントではなく、エンドポイントが応答するリクエストです。受取人IDの確認を参照してください。
受取人IDの確認
Tokenzのウェブショップは、プレイヤーが受取人IDを入力したとき、購入や無料アイテムの受け取りの前にそのIDを確認します。確認のたびに、Tokenzはuser.validationリクエストを送り、その受取人IDのアカウントが存在するかをサーバーに問い合わせます。ただし、以前の応答を再利用できる場合は送りません(応答の再利用を参照)。Tokenzはレスポンスから応答を読み取り、待つのは最大3秒で、再試行はしません。Checkout Sessionを作成しても、APIからでもウェブショップからでも送られません。
リクエストとレスポンスの完全なスキーマは、User validation APIリファレンスを参照してください。
検証URLを設定する
- 設定 > 開発者 > ユーザー検証でURLを設定します。テストとライブには、それぞれ専用のURLと署名シークレットがあるため、先にダッシュボードを目的のモードに切り替えてください。署名シークレットは生成時に一度だけ表示されます。
- Tokenzは
user.validationをこのURLにだけ送ります。webhookのエンドポイントには、すべてのイベントを受け取るエンドポイントであっても送られません。 - サーバーを確認するには、ゲームの受取人IDを入力してテスト検証を送信を選択します。ダッシュボードにサーバーの応答が表示されます。Tokenzは何も保存しません。
- ライブの検証URLを設定するまで、ウェブショップをライブで有効化できません。
ライブのウェブショップでの購入は、ライブのURLで確認されます。testはfalseです。テストのプレビューでの購入は、テストのURLで確認されます。testはtrueです。テストのURLが設定されていない場合、テストのプレビューは入力されたIDを確認せずに受け付けます。
リクエスト
TokenzはJSON形式の本文を含むPOSTリクエストを送信します。
{
"id": "9f8d3c2b-1a4e-4f6d-8b0c-2e5a7d9f1c34",
"object": "user.validation",
"createdAt": "2026-07-22T09:15:00Z",
"test": false,
"credentials": { "type": "recipientId", "recipientId": "player-42931" }
}
idは確認のたびに新しくなります。ログの照合に使い、べき等キーには使わないでください。- テストのURLに送られた確認では
testがtrueです。その場合はテスト用のプレイヤーと照合してください。 credentials.typeはrecipientIdで、現在はこの種類だけです。credentials.recipientIdはプレイヤーが入力した受取人IDです。
リクエストには、イベント配信と同じTokenz-Signatureヘッダーが付き、webhookのエンドポイントではなく検証URLの署名シークレットで作られています。応答する前に、未加工のリクエスト本文に対して検証してください。ウェブフックエンドポイントを保護するを参照してください。
応答
HTTP 200と、プレイヤーが存在するかどうかを返します:
{ "valid": true }
{ "valid": false }
- プレイヤーが存在してもしなくても
200を返してください。Tokenzは2xx以外のステータス(リダイレクトを含む)やvalidのない本文を、不明なプレイヤーではなく障害とみなします。 - 3秒以内に応答してください。時間内に判定が届かないと、プレイヤーは支払えず、もう一度試すよう案内されます。後述の再送とべき等性は、イベントにだけ適用されます。
validと、必要に応じてvalidUntilだけを返し、プレイヤーの詳細情報は含めないでください。プレイヤーは検証に成功したかどうかを知ることができます。Tokenzはサーバーの応答をそのままプレイヤーに転送しません。
応答の再利用
ライブのURLがtrueを返した後、Tokenzは同一プロジェクト内の同じ受取人IDの検証結果を再利用し、サーバーへの問い合わせを省略することがあります。期間はデフォルトで数分です。期間を指定するには、trueの応答に日時のvalidUntilを加えます:
{ "valid": true, "validUntil": "2026-07-22T09:45:00Z" }
falseの応答は再利用されないため、IDを直したプレイヤーはもう一度確認されます。 テストのURLに送られる確認は、常にサーバーに届きます。
再送とべき等性
Tokenz は、Webhook に対してエンドポイントが 2xx レスポンスで受領を通知することを想定しています。それ以外のステータスコードを返した場合、タイムアウトした場合、または到達できなかった場合、Tokenz は最大 3 日間、自動的に配信を再試行します。最初の再試行は、配信失敗から約 5 秒後、15 秒後、30 秒後に行われます。その後は遅延時間を増やし、再試行の頻度を下げます。再試行の時刻は多少変わることがあるため、後続の再試行の正確な時刻に依存しないでください。エンドポイントが 2xx を返すと、そのイベントの再試行は停止します。同じイベントを複数回受信する可能性があり、イベントの到着順序は保証されません。
配信はべき等に処理してください:
- イベントを永続化してから 2xx を返し、時間のかかる処理は非同期で行ってください。
- イベントのトップレベルの
idをべき等キーとして使用してください。処理済みのイベント ID を記録し、すでに処理したイベントはスキップすることで、再送によって注文が二重に履行されることを防げます。
トラブルシューティング:エンドポイントがイベントを受信しない
「Webhook が届かない」場合、そのほとんどは Tokenz が実際に送信しており、エンドポイントがそれを拒否していることを意味します。Tokenz は 2xx 以外のレスポンス(またはタイムアウトや到達できないエンドポイント)を配信の失敗とみなし、最大 3 日間自動的に再試行します。そのため、サーバーに何も届いていないように見えても、Tokenz側では配信が繰り返し失敗している場合があります(例えば HTTP 400 が連続するなど)。
ダッシュボードで配信履歴を確認できる場合は、該当するイベントやエンドポイントを開き、配信状況、HTTPレスポンス、試行履歴を確認してください。閲覧には権限が必要です。配信履歴を利用できない場合は、サーバーのアクセスログとエラーログで調べてください。
1. エンドポイントが返した HTTP ステータスを確認する。 これは Tokenz が見ているものとまったく同じです。サーバーのアクセスログ/エラーログで受信した POST を確認してください。
2xx— イベントは配信され、受領が通知されました。それでもシステムが処理を実行しなかった場合、問題は配信ではなく、レスポンス後のハンドラーにあります。400、401、403— エンドポイントはイベントを受信しましたが、拒否しました(下記を参照)。5xxまたはタイムアウト — ハンドラーがエラーになったか、応答が遅すぎました。
2. 400 を返している場合は、まず署名の検証を確認してください。 これが最も一般的な原因です。
- 生のリクエストボディに対して検証する。 ほとんどのフレームワークは JSON を解析して再シリアライズするため、バイト列が変わり HMAC が一致しなくなります。正確な生のバイト列を(例えば
express.raw()で)読み取り、検証してから解析してください。Webhook エンドポイントを保護する を参照してください。 - 正しい署名シークレットを使用する。 シークレットはエンドポイントを登録するときに一度だけ表示され、そのエンドポイント固有のものです。ローテーションされた、または入力を誤ったシークレットは、すべてのイベントで検証に失敗します。
- テストモードとライブモードを一致させる。 テストモードのイベントをライブの署名シークレットで検証する(またはその逆)と、決して一致しません。1 つのエンドポイントで両方を処理する場合は、イベントの
testフラグを使ってシークレットを選択してください。 - クロックのずれに注意する。 5 分のタイムスタンプ許容時間で拒否している場合、サーバーのクロックが大きくずれていると、本来は有効なイベントを拒否してしまう可能性があります。
3. 2xx 以外のレスポンスになるその他の原因:
- エンドポイントの前段にあるファイアウォール、WAF、または IP 許可リストが Tokenz のリクエストをブロックしている。
- エンドポイントが HTTPS で公開されていない、またはダッシュボードに登録された URL が誤っているか、間違った環境を指している。
- リクエスト処理の途中で重い処理を行ってタイムアウトしている。まず
2xxで受領を通知し、その後に非同期で処理してください。
4. 配信を独立して確認する。 エンドポイント(またはそのコピー)を Webhook.site に向けて、Tokenz が配信していることを確認し、正確なペイロードとヘッダーを検査してから、テストモードの支払いでイベントを発生させてください。
エンドポイントが 2xx を返すと、再試行は停止します。再試行はすでに処理したイベントを再送する可能性があるため、ハンドラーはべき等に保ってください(上記を参照)。