"/hyperbeam/webhook/{activityId}":
    parameters:
        - in: path
          name: activityId
          required: true
          schema: { type: string }
    post:
        tags: [Hyperbeam]
        operationId: hyperbeamCallback
        summary: Hyperbeam access-control callback
        description: |
            Webhook called by the Hyperbeam browser-sharing service to ask cloud_api
            whether a given user / session should be allowed into the shared
            browser. Authenticated by the `hyperbeam-webhook` bearer; never called
            by Bigscreen clients directly.

            Returns 200 with the access decision; non-200 responses are treated as
            denial by Hyperbeam.
        security:
            - hyperbeamApiKey: []
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        description: Hyperbeam-defined webhook payload — see Hyperbeam's docs for the full shape.
                        additionalProperties: true
        responses:
            "200":
                description: Access decision.
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                allowed: { type: boolean }
                                reason:
                                    type: string
                                    description: Reason the request was allowed / denied — surfaced to Hyperbeam logs.
                                userInfo:
                                    type: object
                                    description: Optional user metadata returned to the Hyperbeam session.
                                    additionalProperties: true
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "404":
                description: Activity not found (denial).
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }
