openapi: 3.0.3 info: title: Photon WebHooks and Webservice Contract Custom Authentication Room Lifecycle WebHooks API description: "IMPORTANT SCOPE NOTE: Photon Engine does not publish a general-purpose REST API that developers call. Photon's core products (Realtime, PUN, Fusion, Quantum, Voice, Chat) speak a proprietary binary protocol over UDP, TCP, or WebSocket - modeled separately in asyncapi/photonengine-asyncapi.yml, not here.\nThis document instead models the two genuinely HTTP surfaces in the Photon stack, both of which run in the opposite direction from a typical provider API: Photon's Game Server is the HTTP *client*, and the game developer must implement and host the HTTP *server* that Photon calls.\n1. Room Lifecycle WebHooks - Photon POSTs JSON payloads to a\n developer-configured BaseUrl at points in a room's lifecycle\n (creation, before join, join, leave, custom event, property change,\n close), documented at\n https://doc.photonengine.com/realtime/current/gameplay/web-extensions/webhooks\n and https://doc.photonengine.com/server/current/applications/loadbalancing/webhooks.\n\n2. Custom Authentication - when enabled, Photon's server forwards a\n connecting client's authentication values to a developer-configured\n AuthUrl and expects a JSON verdict, documented at\n https://doc.photonengine.com/realtime/current/connection-and-authentication/authentication/custom-authentication.\n\nThe paths below are written from the developer's point of view: each `path` is an endpoint you implement on your own server, appended to the BaseUrl / AuthUrl you register in the Photon Dashboard. Photon issues the request; your server returns the response. There is no Photon-hosted base URL to call for any of this - `servers` below is a placeholder for your own webhook receiver." version: '1.0' contact: name: Photon Engine url: https://www.photonengine.com license: name: API documentation - Photon Engine Terms of Service url: https://www.photonengine.com/en-us/photon/terms-of-service servers: - url: '{yourBaseUrl}' description: Placeholder for the developer-hosted BaseUrl (WebHooks) or AuthUrl (Custom Authentication) registered in the Photon Cloud Dashboard. Photon calls this host; it is not operated by Photon. variables: yourBaseUrl: default: https://your-service.example.com tags: - name: Room Lifecycle WebHooks description: Endpoints Photon's Game Server calls (HTTP POST) at points in a room's lifecycle. You implement these; Photon is the caller. paths: /Create: post: operationId: handlePathCreate tags: - Room Lifecycle WebHooks summary: PathCreate - room created / state load requested description: Called by Photon when a new room is created, or when an existing persistent room's saved state needs to be loaded (Type "Load"). If the room is persistent and you return a `State` payload, Photon loads it into the room. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookRequestCommon' responses: '200': description: Acknowledgement. Return `State` when responding to a Type "Load" request for a persistent room. content: application/json: schema: $ref: '#/components/schemas/WebhookLoadResponse' /BeforeJoin: post: operationId: handlePathBeforeJoin tags: - Room Lifecycle WebHooks summary: PathBeforeJoin - access control before a player joins description: Called before an actor is allowed to join a room, letting your service approve or deny the join (for example, external ban lists or entitlement checks). requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookRequestCommon' responses: '200': description: ResultCode 0 allows the join; any non-zero ResultCode denies it. content: application/json: schema: $ref: '#/components/schemas/WebhookResultResponse' /Join: post: operationId: handlePathJoin tags: - Room Lifecycle WebHooks summary: PathJoin - player joined an in-memory room description: Called when a player successfully joins a room already in memory. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookRequestCommon' responses: '200': description: Acknowledgement. content: application/json: schema: $ref: '#/components/schemas/WebhookResultResponse' /Leave: post: operationId: handlePathLeave tags: - Room Lifecycle WebHooks summary: PathLeave - player left / disconnected description: Called when a player leaves or disconnects from a room. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookRequestCommon' responses: '200': description: Acknowledgement. content: application/json: schema: $ref: '#/components/schemas/WebhookResultResponse' /Event: post: operationId: handlePathEvent tags: - Room Lifecycle WebHooks summary: PathEvent - client raised a forwarded custom event description: Called when a client raises a custom event with the `HttpForward` web flag set, forwarding the event data to your service. requestBody: required: true content: application/json: schema: allOf: - $ref: '#/components/schemas/WebhookRequestCommon' - type: object properties: Data: type: object additionalProperties: true description: The custom event payload the client raised. responses: '200': description: Acknowledgement. content: application/json: schema: $ref: '#/components/schemas/WebhookResultResponse' /GameProperties: post: operationId: handlePathGameProperties tags: - Room Lifecycle WebHooks summary: PathGameProperties - room or player property changed description: Called when a client sets a room or player property with the `HttpForward` web flag set. requestBody: required: true content: application/json: schema: allOf: - $ref: '#/components/schemas/WebhookRequestCommon' - type: object properties: Properties: type: object additionalProperties: true description: The changed room or player properties. responses: '200': description: Acknowledgement. content: application/json: schema: $ref: '#/components/schemas/WebhookResultResponse' /Close: post: operationId: handlePathClose tags: - Room Lifecycle WebHooks summary: PathClose - room removed from server memory description: Called before Photon removes a room from server memory. `ActorNr`, `UserId`, and `NickName` are not included, unlike other webhook calls. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookRequestCommon' responses: '200': description: Acknowledgement, optionally including final `State` for persistence. content: application/json: schema: $ref: '#/components/schemas/WebhookLoadResponse' components: schemas: WebhookResultResponse: type: object required: - ResultCode properties: ResultCode: type: integer description: 0 indicates success; any non-zero value is treated as a failure. example: 0 Message: type: string description: Optional human-readable message, surfaced in Photon logs on failure. WebhookRequestCommon: type: object description: Fields common to every Room Lifecycle WebHook call except PathClose, which omits ActorNr, UserId, and NickName. required: - AppId - AppVersion - Region - GameId - Type properties: AppId: type: string description: The Photon application ID. AppVersion: type: string description: The client application version. Region: type: string description: The Photon Cloud region the client connected to. GameId: type: string description: The room name/ID the webhook concerns. Type: type: string description: The webhook type, for example "Create", "Load", "Join", "Leave". ActorNr: type: integer description: The actor number of the triggering player (omitted on PathClose). UserId: type: string description: The user ID of the triggering player (omitted on PathClose). NickName: type: string description: The nickname of the triggering player (omitted on PathClose). WebhookLoadResponse: type: object required: - ResultCode properties: ResultCode: type: integer example: 0 Message: type: string State: type: object additionalProperties: true description: Serialized room state, returned on a Type "Load" PathCreate call or an optional PathClose call for persistent rooms.