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.