openapi: 3.0.0 info: title: (title) version: 0.0.0 servers: - url: / paths: /OnMqttClientConnect/DoesNotMatter/DependOnYourEventHandlerSettings: post: description: This event is triggered when the service receive an MQTT CONNECT packet. operationId: OnMqttConnect parameters: - description: "A unique ID generated by the service for each physical connection.\ \ Its format may change, and you shouldn't try to parse it." explode: false in: header name: ce-physicalConnectionId required: true schema: type: string style: simple - explode: false in: header name: ce-eventName required: true schema: enum: - connect type: string style: simple - explode: false in: header name: ce-type required: true schema: enum: - azure.webpubsub.sys.connect type: string style: simple - description: The user the connection authed. explode: false in: header name: ce-userId required: false schema: type: string style: simple - description: The hub the connection belongs to. explode: false in: header name: ce-hub required: true schema: type: string style: simple - description: The connectionId is unique for each client CONNECTION/session. explode: false in: header name: ce-connectionId required: true schema: type: string style: simple - description: The subprotocol the client is using if any. explode: false in: header name: ce-subprotocol required: false schema: type: string style: simple - description: "Defines the state for the connection. You can use the same response\ \ header to reset the value of the state. Multiple `connectionState` headers\ \ aren't allowed. Do base64 encode the string value if it contains complex\ \ characters inside, for example, `base64(jsonString)` to pass complex object\ \ using this attribute." explode: false in: header name: ce-connectionState required: false schema: type: string style: simple - description: "The signature for the upstream webhook to validate if the incoming\ \ request is from the expected origin. The service calculates the value\ \ using both primary access key and secondary access key as the `HMAC` key:\ \ `Hex_encoded(HMAC_SHA256(accessKey, connectionId))`. The upstream should\ \ check if the request is valid before processing it." explode: false in: header name: ce-signature required: false schema: type: string style: simple requestBody: content: application/json: schema: $ref: '#/components/schemas/MqttConnectEventRequest' required: true responses: "200": content: application/json: schema: $ref: '#/components/schemas/MqttConnectEventSuccessResponse' description: The request has succeeded. "202": description: "The request has been accepted for processing, but processing\ \ has not yet completed." "401": content: application/json: schema: $ref: '#/components/schemas/MqttConnectEventFailureResponse' description: Access is unauthorized. "403": content: application/json: schema: $ref: '#/components/schemas/MqttConnectEventFailureResponse' description: Access is forbidden "500": content: application/json: schema: $ref: '#/components/schemas/MqttConnectEventFailureResponse' description: Server error /OnMqttClientConnected/DoesNotMatter/DependOnYourEventHandlerSettings: post: description: "This event is triggered when the service establishes a Web PubSub\ \ CONNECTION(aka. session, not a network connection) with a client." operationId: OnMqttClientConnected parameters: - description: "A unique ID generated by the service for each physical connection.\ \ Its format may change, and you shouldn't try to parse it." explode: false in: header name: ce-physicalConnectionId required: true schema: type: string style: simple - explode: false in: header name: ce-eventName required: true schema: enum: - connected type: string style: simple - explode: false in: header name: ce-type required: true schema: enum: - azure.webpubsub.sys.connected type: string style: simple - explode: false in: header name: ce-sessionId required: true schema: type: string style: simple - description: The user the connection authed. explode: false in: header name: ce-userId required: false schema: type: string style: simple - description: The hub the connection belongs to. explode: false in: header name: ce-hub required: true schema: type: string style: simple - description: The connectionId is unique for each client CONNECTION/session. explode: false in: header name: ce-connectionId required: true schema: type: string style: simple - description: The subprotocol the client is using if any. explode: false in: header name: ce-subprotocol required: false schema: type: string style: simple - description: "Defines the state for the connection. You can use the same response\ \ header to reset the value of the state. Multiple `connectionState` headers\ \ aren't allowed. Do base64 encode the string value if it contains complex\ \ characters inside, for example, `base64(jsonString)` to pass complex object\ \ using this attribute." explode: false in: header name: ce-connectionState required: false schema: type: string style: simple - description: "The signature for the upstream webhook to validate if the incoming\ \ request is from the expected origin. The service calculates the value\ \ using both primary access key and secondary access key as the `HMAC` key:\ \ `Hex_encoded(HMAC_SHA256(accessKey, connectionId))`. The upstream should\ \ check if the request is valid before processing it." explode: false in: header name: ce-signature required: false schema: type: string style: simple requestBody: content: application/json: schema: type: object required: true responses: "200": description: The request has succeeded. /OnMqttClientDisconnected/DoesNotMatter/DependOnYourEventHandlerSettings: post: description: "This event is triggered when a Web PubSub CONNECTION(aka. session,\ \ not a network connection) is ended." operationId: OnMqttClientDisconnected parameters: - description: "A unique ID generated by the service for each physical connection.\ \ Its format may change, and you shouldn't try to parse it." explode: false in: header name: ce-physicalConnectionId required: true schema: type: string style: simple - explode: false in: header name: ce-eventName required: true schema: enum: - disconnected type: string style: simple - explode: false in: header name: ce-type required: true schema: enum: - azure.webpubsub.sys.disconnected type: string style: simple - explode: false in: header name: ce-sessionId required: true schema: type: string style: simple - description: The user the connection authed. explode: false in: header name: ce-userId required: false schema: type: string style: simple - description: The hub the connection belongs to. explode: false in: header name: ce-hub required: true schema: type: string style: simple - description: The connectionId is unique for each client CONNECTION/session. explode: false in: header name: ce-connectionId required: true schema: type: string style: simple - description: The subprotocol the client is using if any. explode: false in: header name: ce-subprotocol required: false schema: type: string style: simple - description: "Defines the state for the connection. You can use the same response\ \ header to reset the value of the state. Multiple `connectionState` headers\ \ aren't allowed. Do base64 encode the string value if it contains complex\ \ characters inside, for example, `base64(jsonString)` to pass complex object\ \ using this attribute." explode: false in: header name: ce-connectionState required: false schema: type: string style: simple - description: "The signature for the upstream webhook to validate if the incoming\ \ request is from the expected origin. The service calculates the value\ \ using both primary access key and secondary access key as the `HMAC` key:\ \ `Hex_encoded(HMAC_SHA256(accessKey, connectionId))`. The upstream should\ \ check if the request is valid before processing it." explode: false in: header name: ce-signature required: false schema: type: string style: simple requestBody: content: application/json: schema: $ref: '#/components/schemas/MqttDisconnectedEventRequest' required: true responses: "200": description: The request has succeeded. components: parameters: CommonRequestHeaders.connectionId: description: The connectionId is unique for each client CONNECTION/session. explode: false in: header name: ce-connectionId required: true schema: type: string style: simple CommonRequestHeaders.connectionState: description: "Defines the state for the connection. You can use the same response\ \ header to reset the value of the state. Multiple `connectionState` headers\ \ aren't allowed. Do base64 encode the string value if it contains complex\ \ characters inside, for example, `base64(jsonString)` to pass complex object\ \ using this attribute." explode: false in: header name: ce-connectionState required: false schema: type: string style: simple CommonRequestHeaders.hub: description: The hub the connection belongs to. explode: false in: header name: ce-hub required: true schema: type: string style: simple CommonRequestHeaders.signature: description: "The signature for the upstream webhook to validate if the incoming\ \ request is from the expected origin. The service calculates the value using\ \ both primary access key and secondary access key as the `HMAC` key: `Hex_encoded(HMAC_SHA256(accessKey,\ \ connectionId))`. The upstream should check if the request is valid before\ \ processing it." explode: false in: header name: ce-signature required: false schema: type: string style: simple CommonRequestHeaders.subprotocol: description: The subprotocol the client is using if any. explode: false in: header name: ce-subprotocol required: false schema: type: string style: simple CommonRequestHeaders.userId: description: The user the connection authed. explode: false in: header name: ce-userId required: false schema: type: string style: simple schemas: ClientCertificateInfo: allOf: - additionalProperties: {} type: object properties: thumbprint: description: The thumbprint of the client certificate. type: string content: description: The content of the client certificate in PEM format. type: string required: - content - thumbprint type: object ConnectEventRequest: allOf: - additionalProperties: {} type: object description: Represents a request for a connection event. properties: claims: additionalProperties: items: type: string type: array type: object query: additionalProperties: items: type: string type: array type: object headers: additionalProperties: items: type: string type: array type: object subprotocols: items: type: string type: array clientCertificates: items: $ref: '#/components/schemas/ClientCertificateInfo' type: array required: - claims - clientCertificates - headers - query - subprotocols type: object DisconnectEventRequest: description: Represents a request for a disconnection event. properties: reason: type: string required: - reason type: object EmptyConnectedEventRequest: type: object MqttConnectEventFailureResponse: description: Represents the response properties of an MQTT connection failure. example: mqtt: reason: reason code: 0 userProperties: - name: name value: value - name: name value: value properties: mqtt: $ref: '#/components/schemas/MqttConnectEventFailureResponseProperties' required: - mqtt type: object MqttConnectEventFailureResponseProperties: description: Represents the properties of an MQTT connection failure response. example: reason: reason code: 0 userProperties: - name: name value: value - name: name value: value properties: code: description: "The failure code. It will be sent to the clients in the CONNACK\ \ packet as a return code (MQTT 3.1.1) or reason code (MQTT 5.0). Upstream\ \ webhook should select a valid integer value defined the MQTT protocols\ \ according to the protocol versions of the clients. If Upstream webhook\ \ sets an invalid value, clients will receive \"unspecified error\" in\ \ the CONNACK packet." type: integer reason: description: The reason for the failure. It's a human readable failure reason string designed for diagnostics. It will be sent to those clients whose protocols support reason string in the CONNACK packet. Now only MQTT 5.0 supports it. type: string userProperties: description: "The user properties associated with the failure. They'll be\ \ converted to user properties in the CONNACK packet, and sent to clients\ \ whose protocols support user properties. Now only MQTT 5.0 supports\ \ user properties. Upstream webhook can use the property for additional\ \ diagnostic or other information." items: $ref: '#/components/schemas/MqttUserProperty' type: array required: - code type: object MqttConnectEventProperties: allOf: - additionalProperties: {} type: object description: Represents the properties of an MQTT connection. example: password: password userProperties: - name: name value: value - name: name value: value protocolVersion: 0 username: username properties: protocolVersion: description: |- MQTT protocol version. The same as the CONNECT packet's ProtocolVersion. MQTT 3.1.1 is 4, MQTT 5.0 is 5. type: integer username: description: The username field in the MQTT CONNECT packet. type: string password: description: The base64 encoded password field in the MQTT CONNECT packet. type: string userProperties: description: The user properties in the MQTT CONNECT packet. items: $ref: '#/components/schemas/MqttUserProperty' type: array required: - protocolVersion type: object MqttConnectEventRequest: allOf: - $ref: '#/components/schemas/ConnectEventRequest' description: Represents a request for an MQTT connection event. example: mqtt: password: password userProperties: - name: name value: value - name: name value: value protocolVersion: 0 username: username properties: mqtt: $ref: '#/components/schemas/MqttConnectEventProperties' required: - mqtt type: object MqttConnectEventSuccessResponse: allOf: - additionalProperties: {} type: object description: Represents a successful response to an MQTT connection event. example: subprotocol: subprotocol roles: - roles - roles mqtt: userProperties: - name: name value: value - name: name value: value groups: - groups - groups userId: userId properties: roles: description: The property provides a way for the upstream Webhook to authorize the client. There are different roles to grant initial permissions for PubSub WebSocket clients. See details in https://learn.microsoft.com/azure/azure-web-pubsub/concept-client-protocols#permissions items: type: string type: array subprotocol: description: It should be "mqtt" or omitted. type: string userId: description: "As the service allows anonymous connections, it's the connect\ \ event's responsibility to tell the service the user ID of the client\ \ connection. The service reads the user ID from the response payload\ \ userId if it exists." type: string groups: description: "Initial groups the client joins. The property provides a convenient\ \ way for user to add the client to one or multiple groups. In this way,\ \ there's no need to have another call to add this connection to some\ \ groups." items: type: string type: array mqtt: $ref: '#/components/schemas/MqttConnectEventSuccessResponseProperties' type: object MqttConnectEventSuccessResponseProperties: description: Represents the MQTT specific properties in a successful MQTT connection event response. example: userProperties: - name: name value: value - name: name value: value properties: userProperties: description: "It's additional diagnostic or other information provided by\ \ upstream server. They'll be converted to the user properties field in\ \ the CONNACK packet, and sent to clients whose protocols support user\ \ properties. Now only MQTT 5.0 supports user properties. Upstream webhook\ \ can use the property to communicate additional diagnostic or other information\ \ with clients." items: $ref: '#/components/schemas/MqttUserProperty' type: array type: object MqttDisconnectPacketProperties: description: Represents the properties of an MQTT DISCONNECT packet. properties: code: description: |- The DISCONNECT reason code defined in MQTT 5.0 spec. For MQTT 3.1.1 clients, it's always the default value 0. type: integer userProperties: description: |- The user properties in the DISCONNECT packet sent by the client. The value is not null only if the client sent a DISCONNECT packet with user properties. items: $ref: '#/components/schemas/MqttUserProperty' type: array required: - code type: object MqttDisconnectedEventProperties: description: Represents the properties of an MQTT disconnection event. example: disconnectPacket: "" initiatedByClient: true properties: initiatedByClient: description: Indicates whether the disconnection is initiated by the client. type: boolean disconnectPacket: allOf: - $ref: '#/components/schemas/MqttDisconnectPacketProperties' description: |- The DISCONNECT packet properties to end the last physical connection. It may be sent by the client or server. required: - initiatedByClient type: object MqttDisconnectedEventRequest: allOf: - $ref: '#/components/schemas/DisconnectEventRequest' description: Represents a request for an MQTT disconnection event. example: mqtt: disconnectPacket: "" initiatedByClient: true properties: mqtt: $ref: '#/components/schemas/MqttDisconnectedEventProperties' required: - mqtt type: object MqttUserProperty: allOf: - additionalProperties: {} type: object description: Represents a user property in an MQTT connection. example: name: name value: value properties: name: type: string value: type: string required: - name - value type: object