Webhooks

概要

Webhookは、信頼できるゲーム設定やルーム構成の情報源として主に利用され、オンラインアプリケーションの安全性向上に大きく寄与します。

デフォルトのクラウドプラグインは、AppIDダッシュボードで定義されたさまざまなWebhookをサポートしています。設定と有効化を行うと、Photon CloudはカスタムバックエンドへHTTP POSTリクエストを送信し、そのレスポンスデータ（JSON）を活用して、ルームやゲームセッションの各種構成を適用します。

セットアップ

WebhookはPhotonダッシュボード上でAppIdごとにセットアップを行います。

1. Photon Dashboard へナビゲートし、ログインする。
2. AppIdを探し、Manageをクリックする。
3. プラグインまでスクロールで下がり、Editをクリックする。
4. Add New Pairをクリックして、keysとvalues (各設定値に使えるのは最大1024文字)を追加する。
5. Saveを押下して最大1分間待ち変更が反映されたことを確認する。

ダッシュボード設定

Key	Type	Example	Description
WebHookBaseUrl	string	https://localhost:3581	カスタムバックエンドの基本URLです。WebhookのパスはこのURLに追加され、次の形式になります: {WebHookBaseUrl}/game/create 必ず設定してください。
WebHookIntegration	string	Default	選択されたWebhookの統合方法です（デフォルトは `Default`）。 選択肢は以下の通りです： Default、PlayFab
WebHookSecret	string	**********	これらは各Webリクエストとともに送信され、リクエストの認証に利用できます。 ヘッダー名は `X-SecretKey` に設定されます。
WebHookCustomHttpHeaders	Dictionary <string, string>	{"A": "Foo", "B": "100" }	`JSON`形式の辞書です。すべてのエントリーはカスタムWebリクエストのヘッダーに追加されます。ダブルクォーテーションを使用してください。
WebHookEnableOnCreate	bool	true	これを`true`に設定すると、クライアントがゲームセッションを作成するときに`CreateGame`Webhookが発動します。
WebHookEnableOnClose	bool	false	これを`true`に設定すると、ゲームセッションが閉じられた際に `CloseGame` Webhookが発動します。
WebHookEnableOnJoin	bool	true	これを`true`に設定すると、クライアントがゲームセッションに参加しようとした際に`JoinGame` Webhookが発動します。
WebHookEnableOnLeave	bool	false	これを`true`に設定すると、クライアントがゲームセッションを退出した際に `LeaveGame` Webhookが発動します。
WebHookUrl{KEY}	string	https://foo.net/path	このパターンは任意で、`WebHookBaseUrl`に基づいて個別のWebhookのデフォルトパスを上書きするために使用できます。 `{KEY}` の有効な置換文字列は、`OnCreate`、`OnJoin`、`OnLeave`などです。

Webhook API

WebhooksはJSONコンテンツを送信し、レスポンスもJSON形式のコンテンツのみを受け付けます。JSONの文字エンコーディングはUTF-8のみが必須です。

WebhooksはHTTPレスポンスコードとして200または400を期待しています。

• 200: リクエスト成功
• 400: エラーまたは操作が拒否された（例：クライアントによるルームやゲームセッションの作成を許可しない場合）

Photonサーバーは、通信エラー時にWebhookのリトライを3回行います。リトライ間の遅延は、400ms、1600ms、6400msです。また、リクエストが失敗し再試行されないまでのタイムアウト時間は10秒です。

エラーの詳細情報をPhotonプラグインに返すために、WebhookErrorの定義を記入してください。これにより、以下の用途に利用できます：

• ロギング
• クライアントへの情報返還
• カスタムプラグインによる高度なエラー処理

Httpリクエスト再試行

Photonサーバーは、バックエンドからの再試行可能なエラー応答に対して、リクエストをさらに3回再送信します。

その後のリクエストには、それらを識別するための異なるヘッダーが付加されます。

EGRepeatId - 例えば、0、1、2、3などの整数値で、リクエストの再送番号。
EGInvokeId - リクエストID (整数)

よくあるリクエストヘッダ

Tこれらの共通リクエストヘッダーは、すべての ウェブリクエストに追加されます。

Name	Type	Content	Description
Accept	string	application/json	Webhooksは、レスポンス本文として JSON 形式のみを受け付けます
Accept-Charset	string	utf-8	Webhooksは、レスポンスの本文の文字エンコーディングとしてUTF-8のみを受け付けます
Content-Type	string	application/json	すべてのWebhooksは、 JSON 形式の本文データを送信します
X-SecretKey	string	**********	このキーはカスタムバックエンドのみが知っているべきものであり、受信するウェブリクエストの認証に使われます。PhotonダッシュボードでWebHookSecretと設定されます。
X-Origin	string	Photon	必ず"Photon"と設定

CreateGame

このWebhookは、ルームまたはゲームセッションがPhotonサーバー上で作成される前に呼び出されます。Webhookがレスポンスを受け取るまで作成はブロックされるため、これによりクライアントが接続を確立するまでの時間に影響します。

CreateGameWebhookは、常にルームまたはゲームセッションの作成を開始したユーザーのJoinGameリクエストとして扱われます。このユーザーに対して後続のJoinGameWebhookは発生しません。このWebhookは、JoinGameWebhookのデータを共有します。

このWebhookを設定するには、PhotonダッシュボードでWebHookBaseUrlとWebHookEnableCreateGameを設定している必要があります。

JavaScript

POST https://{WebHookBaseUrl}/game/create

CreateGameリクエスト

Name	Type	Example	Description
AppId	string	d1f67eec-51fb-45c1	The Photon AppId.
AppVersion	string	1.0-live	ルームまたはゲームセッションの作成時に使用されるアプリバージョンです。
Region	string	eu	ルームまたはゲームセッションが作成されたゲームサーバーのリージョンコードです。.
Cloud	string	1	そのゲームサーバーが稼働しているCloud Idです。
UserId	string	db757806-8570-45aa	ルームまたはゲームセッションを作成したクライアントのUserIdです。
AuthCookie	Dictionary<string, object>	db757806-8570-45aa	バックエンドによって設定されたPhotonのカスタム認証クッキーです。
RoomName	string	e472a861-a1e2-49f7	ルームまたはゲームセッションの名前です.
GameId	string	0:eu:e472a861-a1e2-49f7	GameIdは、 {Cloud:}{Region:}RoomNameで構成される一意のIDです。レスポンスによって上書きされることがあります。
EnterRoomParams	EnterRoomParams	JSON: EnterRoomParamセクションをご覧ください	クライアントから送信されたPhotonのルームまたはゲームセッションのオプションです

Jsonの例:

JSON

{
  "AppId": "d1f67eec-51fb-45c1",
  "AppVersion": "1.0-live",
  "Region": "eu",
  "Cloud": "1",
  "UserId": "db757806-8570-45aa",
  "AuthCookie": {
    "Secret": "**********"
  }
  "RoomName": "e472a861-a1e2-49f7",
  "GameId": "0:eu:e472a861-a1e2-49f7",
  "EnterRoomParams": {
    "RoomOptions": {
      "IsVisible": true,
      "IsOpen": true
    }
  }
}

HTTP応答コード

Name	Type	Description
200 OK	CreateGame応答	ルームまたはゲームセッションの作成は開始されますが、レスポンスの設定データによってクライアントから送信されたデータが上書きされます。
400 Bad Request	WebhookError	ルームまたはゲームセッションの作成は許可されず、キャンセルされます。クライアントはエラーを受け取ります。

CreateGame応答

Name	Type	Description
GameId	string	後続のウェブリクエストで使用される `GameId` を上書きします。 値は `null` もしくは省略可能です。
EnterRoomParams	EnterRoomParams	作成時に選択したルームオプションを強制適用します。 JSONオブジェクトには、上書きしたいメンバーだけを含める必要があり、すべてのメンバーを含める必要はありません。 最初のオプションは、`EnterRoomParams`を送信することで保護されます。ほとんどの設定は、クライアントがPhotonのルームプロパティを送信して変更することが可能です。これを防ぐには、Photonダッシュボードの `BlockRoomProperties`設定を有効にしてください。 値は `null` もしくは省略可能です。

Json Example:

JSON

{
  "GameId": "0:eu:db757806-8570-45aa",
  "EnterRoomParams": {
    "RoomOptions": {
      "CustomRoomProperties": {
        "GameType": "CUSTOM_GAME_TYPE",
        "CustomData": 101
      }
    }
  }
}

JoinGame

JoinGameWebhookは、クライアントが既存のルームやゲームセッションに参加する前に送信されます。
参加を許可する場合は200を返し、キャンセルする場合は400を返してください。

このWebhookを有効にするには、PhotonアプリIDダッシュボードでWebHookBaseUrlとWebHookEnableOnJoinを設定する必要があります。

JavaScript

POST https://{WebHookBaseUrl}/game/join

JoinGameリクエスト

Name	Type	Example	Description
AppId	string	d1f67eec-51fb-45c1	Photon AppId
GameId	string	0:eu:db757806-8570-45aa	一意のGameId
UserId	string	db757806-8570-45aa	Photon UserId
AuthCookie	Dictionary<string, object>	db757806-8570-45aa	バックエンドによって設定されたPhotonのカスタム認証クッキーです。

Jsonの例:

JSON

{
  "AppId": "*******************",
  "GameId": "0:eu:db757806-8570-45aa",
  "UserId": "db757806-8570-45aa",
  "AuthCookie": {
    "Secret": "**********"
  }
}

HTTP応答コード

Name	Type	Description
200 OK	JoinGame Response	クライアントがルームに参加します。
400 Bad Request	WebhookError	ルームへの参加は失敗します。

JoinGame応答

Json Example:

JSON

{
  // empty
}

LeaveGame

LeaveGameWebhookは、クライアントが既存のルームまたはゲームセッションを離れた後に送信されます。

このWebhookを有効にするには、PhotonアプリIDダッシュボードでWebHookBaseUrlとWebHookEnableOnLeaveを設定してください。

JavaScript

POST https://{WebHookBaseUrl}/game/leave

LeaveGameリクエスト

Name	Type	Example	Description
AppId	string	d1f67eec-51fb-45c1	Photon AppId
GameId	string	0:eu:db757806-8570-45aa	一意のGameId
UserId	string	db757806-8570-45aa	Photon UserId
ActorNr	int	db757806-8570-45aa	Photonサーバーが割り当てるアクター番号で、クライアントごとにインクリメントされるランタイムIDです。
AuthCookie	Dictionary<string, object>	db757806-8570-45aa	Photon UserId
IsInactive	bool	db757806-8570-45aa	プレイヤーがルームを離れたが、Player TTLが設定されている場合などで、まだ非アクティブとしてマークされているときに`true`に設定されます。この状態では、追加の`LeaveGame`リクエストが続けて送信されることがあります。

Jsonの例:

JSON

{
  "AppId": "*******************",
  "GameId": "0:eu:db757806-8570-45aa",
  "UserId": "db757806-8570-45aa",
  "ActorNr": 1,
  "AuthCookie": {
    "Secret": "**********"
  },
  "IsInactive": false
}

HTTP Response Codes

Name	Type	Description
200 OK	LeaveGame Response	受信の確認のみ。
400 Bad Request	WebhookError	エラーが無視されます。Photon Cloudにログされるだけです。

LeaveGameレスポンス

Jsonの例:

JSON

{
  // empty
}

CloseGame

CloseGame webhookは、クライアント全員が退出した後、ルーム/ゲームセッションが閉じられると送信されます。
Photonダッシュボード上でWebHookBaseUrlおよびWebHookEnableOnCloseの設定が必須です。

JavaScript

POST https://{WebHookBaseUrl}/game/close

CloseGameリクエスト

Name	Type	Example	Description
AppId	string	d1f67eec-51fb-45c1	The Photon AppId
GameId	string	0:eu:db757806-8570-45aa	Unique game id
CloseReason	int (CloseReason)	0	The reason why this room/session has been closed.

Json Example:

JSON

{
  "GameId": "0:eu:db757806-8570-45aa",
  "CloseReason": 0
}

HTTP応答コード

Name	Type	Description
200 OK		Confirmation of receipt.

CloseReason

Name	Value	Description
Ok	0	Session was closed without errors.
FailedOnCreate	1	Session was closed because it failed to Create.

Name	Value	Description
ExceptionOnUpdateLoop	101	Any exception occurred on the Plugin Server Update Loop, causing the Session to be closed.
ExceptionOnHostMigration	102	Any exception while performing the Host Migration on the Plugin side.
ServerHasDisconnected	103	Fusion Server has disconnected from the Session, all clients must be disconnected.
FailedToSetupServer	104	Any exception while performing the Plugin Server Setup, causing the Session to be closed.
FailedToParseNetworkProjectConfig	105	Failed to parse the Fusion's NetworkProjectConfig.

EnterRoomParams

この定義は、Photon RealtimeのEnterRoomParamsクラスに似せて設計されています。CreateGameWebhookで設定可能なすべてのオプションを含んでいます。JSONレスポンスを作成する際は、すべてのメンバーが任意であり、nullまたは未設定にすることも可能です。

Name	Type	Description
RoomOptions	RoomOptions	RoomOptionsオブジェクト
ExpectedUsers	string[]	ルームまたはセッションに参加を許可するUserIdsの一覧です（ルームを作成したユーザーに加えて）。 もしMaxPlayersが記載されたExpectedUsersの数より大きい場合は、未予約の枠に任意のプレイヤーが参加して埋めることができます。 これはRoomJoin()のみに有効で、JoinRandom()には適用されません。

Jsonの例:

JSON

{
  "RoomOptions": {
    "IsVisible": true,
    "IsOpen": true,
    "MaxPlayers": 8,
    "PlayerTtl": null,
    "EmptyRoomTtl": 10000,
    "CustomRoomProperties": {
      "Foo": "bar",
      "PlayerClass": 1
    },
    "CustomRoomPropertiesForLobby": [
      "Foo"
    ],
    "SuppressRoomEvents": null,
    "SuppressPlayerInfo": null,
    "PublishUserId": null,
    "DeleteNullProperties": null,
    "BroadcastPropsChangeToAll": null,
    "CleanupCacheOnLeave": null,
    "CheckUserOnJoin": null
  },
  "ExpectedUsers": [
    "A",
    "B",
    "C"
  ]
}

Hint

Fusion only supports overriding the RoomOptions.CustomRoomProperties of a Game Session. All other fields are ignored if returned to the Photon Cloud.

RoomOptions

すべての値はnull許容型であり、Quantumサーバーに返信する際にnullに設定したり、省略したりすることが可能です。その場合、このレスポンスは該当するルームプロパティを変更せず、デフォルトの値のままか、ルーム作成時にクライアントが送信した値が維持されます。

Name	Type	Description
IsVisible	bool	このルームがPhotonのマッチメイキングにリストされるかどうかを定義します。
IsOpen	bool	このルームに他のクライアントが参加できるかどうかを定義します。
MaxPlayers	byte	任意の時点でルーム内に入れる最大プレイヤー数です。0は「制限なし」を意味します。
PlayerTtl	int	ルーム内の「アクター」の生存時間（TTL）をミリ秒単位で設定します。クライアントが切断された場合、このアクターは最初に非アクティブとなり、指定されたタイムアウト後に削除されます。
EmptyRoomTtl	int	最後のプレイヤーが退室した後のルームの生存時間（TTL）をミリ秒単位で設定します。これは、プレイヤーが近いうちに再参加する場合にルームをメモリ内に保持しておくためのものです。
CustomRoomProperties	Dictionary <string, object>	ルーム作成時に設定されるカスタムプロパティです。
CustomRoomPropertiesForLobby	string[]	ロビーにリストされるカスタムルームプロパティを定義します。 これらのプロパティの値の型は bool, byte, short, int, long または stringである必要があります。 最大プロパティ数は 3 です。 文字列値の最大長は 64 文字です。 キーの制限は、Photonダッシュボードの設定AllowedLobbyPropertiesによっても適用可能です。
SuppressRoomEvents	bool	サーバーに対して、参加および退出するプレイヤーのルームイベントをスキップするよう指示します。 デフォルトは false です。
SuppressPlayerInfo	bool	サーバー側での参加と退出のイベントおよびルーム内のプロパティブロードキャストを無効にします（通信量を最小化するため）。 デフォルトは false です。
PublishUserId	bool	プレイヤーのUserIdsをルーム内で「公開」するかどうかを設定します。 これは、FindFriendsの機能を利用したり、プレイヤー同士が別のゲームで一緒にプレイしたい場合に役立ちます。 デフォルトは false です。
DeleteNullProperties	bool	オプションとして、値に null を割り当てると、そのプロパティが削除されます。 デフォルトは false です。/td>

Name	Type	Description
CleanupCacheOnLeave	bool	Removes a user's events and properties from the room when a user leaves. Should always be true.
CheckUserOnJoin	bool	By default, property changes are sent back to the client that's setting them to avoid de-sync when properties are set concurrently. Should always be true.

WebhookError

Name	Type	Description
Status	int	HTTPステータスコード
Error	string	エラー名
Message	string	エラーメッセージ

Jsonの例:

JSON

{
  "Status": 400,
  "Error": "PlayerNotAllowed",
  "Message": "LoremIpsum"
}

PlayFab

PlayFabと連携させるには、WebHookIntegrationダッシュボード変数を追加し、その値をPlayFabに設定してください。

• パス内のすべてのスラッシュ（/）はアンダースコア（_）に置き換えられます。例：game/create → game_create
• すべてのWebhookリクエストには、WebHooksConfig.AppIdによって制御されるAppIdプロパティが自動的に追加されます（欠落している場合）。
• すべてのWebhookリクエストには、UserIdプロパティが自動的に追加され、欠落している場合は"0"が設定されます。
• Webhookのレスポンスは、以下のJson結果ボディを処理し、ResultCodeが0以外の場合にWebhookを失敗とみなします。エラー時には、MessageがWebHookError.Messageにコピーされます。

JSON

{
    "ResultCode": 0,
    "Message": "success"
}

Photon CloudのWebリクエスト制限

デフォルトでは、PhotonサーバーはHTTPリクエストを直列に管理し、現在のリクエストが完了するまで新たなリクエストは開始されません。新しいリクエストはキューに追加されます。この制限は各ルームごとに適用されます。

このため、OnJoinやAddPlayerのWebhookを使用している場合、高いプレイヤー数やPhotonクラウドとカスタムバックエンド間のラウンドトリップタイムが長い場合に、予期しない待ち時間が発生する可能性があります。

並列リクエストはエンタープライズクラウドで有効にでき、また、公開クラウドアプリ向けにも選択制の対応を検討中です。

その他の制限は以下の通りです。

• HttpRequestTimeout: 30000
• LimitHttpResponseMaxSize: 200000
• MaxQueuedRequests: 5000

Back to top