Azure Web PubSub Client and Upstream Events

asyncapi: 2.6.0
id: urn:com:microsoft:azure:webpubsub
info:
  title: Azure Web PubSub
  version: 1.0.0
  description: "Azure Web PubSub is a fully managed real-time messaging service from\n\
    Microsoft Azure that lets clients exchange publish/subscribe messages\nover WebSockets\
    \ without operating WebSocket infrastructure. Clients\nconnect to the service\
    \ over secure WebSocket (`wss://`) and may either\nuse a simple WebSocket frame\
    \ (text/binary) or upgrade to one of the\nJSON publish/subscribe subprotocols:\n\
    \n- `json.webpubsub.azure.v1` — JSON pub/sub subprotocol that lets a\n  *PubSub\
    \ WebSocket client* join groups, publish to groups, and route\n  custom events\
    \ to upstream event handlers directly through the\n  service.\n- `json.reliable.webpubsub.azure.v1`\
    \ — Reliable variant of the JSON\n  pub/sub subprotocol that adds `sequenceId`\
    \ on every server-to-client\n  `message` and requires the client to acknowledge\
    \ with a\n  `sequenceAck`. Also returns `reconnectionToken` on `connected` so\n\
    \  clients can recover sessions across intermittent network failures\n  using\
    \ the `awps_connection_id` / `awps_reconnection_token` query\n  parameters.\n\n\
    The server side of an Azure Web PubSub solution receives client\nactivity as **upstream\
    \ events** delivered by the service to a\nconfigured webhook endpoint using the\
    \ CloudEvents 1.0 HTTP binding\n(binary content mode). Event types are namespaced\n\
    `azure.webpubsub.sys.*` for system events (`connect`, `connected`,\n`disconnected`)\
    \ and `azure.webpubsub.user.*` for user events\n(`message` for simple clients\
    \ and `<custom_event>` for PubSub\nsubprotocol clients sending `type: event` frames).\
    \ Web PubSub also\nadvertises an Event Grid integration where events are published\
    \ with\n`eventType` values like `Microsoft.SignalRService.ClientConnectionConnected`\n\
    and `Microsoft.SignalRService.ClientConnectionDisconnected`; the\nCloudEvents\
    \ `ce-type` values delivered by the Web PubSub event handler\n(Webhook upstream)\
    \ however use the `azure.webpubsub.*` namespace as\ndocumented at\nhttps://learn.microsoft.com/en-us/azure/azure-web-pubsub/reference-cloud-events\n\
    and modeled below.\n\nThis AsyncAPI document models only the documented surface\
    \ area of the\nJSON WebSocket subprotocols and the CloudEvents HTTP upstream\n\
    contract. Fields not documented by Microsoft (for example, undocumented\nsubprotocol\
    \ message types, undocumented CloudEvents extensions, or\nREST data-plane operations\
    \ — which are modeled separately in OpenAPI)\nare intentionally NOT included.\n"
  contact:
    name: Azure Web PubSub Documentation
    url: https://learn.microsoft.com/en-us/azure/azure-web-pubsub/
  license:
    name: Microsoft Terms of Use
    url: https://www.microsoft.com/en-us/legal/terms-of-use
defaultContentType: application/json
servers:
  client:
    url: wss://{instance}.webpubsub.azure.com
    protocol: wss
    description: 'Azure Web PubSub client endpoint. Clients open a WebSocket

      connection to `wss://{instance}.webpubsub.azure.com/client/hubs/{hub}`

      and optionally specify one of the supported subprotocols via the

      `Sec-WebSocket-Protocol` header. Authentication is performed with a

      short-lived JWT access token passed as the `access_token` query

      parameter (generated by the service''s REST data plane or a server

      SDK).

      '
    variables:
      instance:
        default: example
        description: Web PubSub service instance name
    security:
    - clientAccessToken: []
  upstream:
    url: https://{upstreamHost}
    protocol: https
    description: 'Customer-owned HTTP endpoint registered as an event handler on the

      hub. The Web PubSub service delivers client events to this endpoint

      using the CloudEvents 1.0 HTTP protocol binding (binary content

      mode). The endpoint must implement CloudEvents abuse-protection

      handshake by returning `WebHook-Allowed-Origin` in response to the

      `WebHook-Request-Origin` validation request.

      '
    variables:
      upstreamHost:
        default: contoso.example.com
        description: Customer-controlled upstream webhook host
channels:
  /client/hubs/{hub}:
    description: 'WebSocket channel between a single client and a hub on the Web

      PubSub service instance. Each connection belongs to exactly one

      hub. Messages on this channel are JSON frames defined by the

      `json.webpubsub.azure.v1` or `json.reliable.webpubsub.azure.v1`

      subprotocol. Simple WebSocket clients (no subprotocol) exchange

      raw text/binary frames instead and are NOT modeled here — refer

      to the user event handler contract on the `upstream` server for

      how their frames surface to the application backend.

      '
    servers:
    - client
    parameters:
      hub:
        description: Hub name. Hubs provide logical isolation within an instance.
        schema:
          type: string
    bindings:
      ws:
        bindingVersion: 0.1.0
        query:
          type: object
          description: Query string parameters supported on the connect handshake.
          properties:
            access_token:
              type: string
              description: JWT access token authorizing the client connection.
            awps_connection_id:
              type: string
              description: 'Reliable subprotocol only. Previously-issued connection

                id used to recover a dropped session.

                '
            awps_reconnection_token:
              type: string
              description: 'Reliable subprotocol only. Token returned on the

                original `connected` system message; required to recover

                a dropped session.

                '
        headers:
          type: object
          properties:
            Sec-WebSocket-Protocol:
              type: string
              enum:
              - json.webpubsub.azure.v1
              - json.reliable.webpubsub.azure.v1
              description: 'Optional subprotocol negotiation. If omitted the

                connection behaves as a *simple WebSocket client* and

                frames are passed through to the upstream event handler

                as `azure.webpubsub.user.message` events. If present,

                the client may exchange the JSON pub/sub frames defined

                in this document.

                '
    publish:
      operationId: clientSend
      summary: Messages a client sends to the service over the JSON pub/sub subprotocol.
      message:
        oneOf:
        - $ref: '#/components/messages/JoinGroup'
        - $ref: '#/components/messages/LeaveGroup'
        - $ref: '#/components/messages/SendToGroup'
        - $ref: '#/components/messages/SendEvent'
        - $ref: '#/components/messages/Ping'
        - $ref: '#/components/messages/SequenceAck'
    subscribe:
      operationId: clientReceive
      summary: Messages the service sends back to the client.
      message:
        oneOf:
        - $ref: '#/components/messages/AckResponse'
        - $ref: '#/components/messages/MessageFromGroup'
        - $ref: '#/components/messages/MessageFromServer'
        - $ref: '#/components/messages/SystemConnected'
        - $ref: '#/components/messages/SystemDisconnected'
        - $ref: '#/components/messages/Pong'
  /upstream:
    description: 'CloudEvents 1.0 HTTP delivery channel from the Web PubSub service

      to the customer-configured upstream webhook. The service POSTs

      one HTTP request per client event, using CloudEvents *binary*

      content mode (CloudEvents attributes are conveyed in `ce-*` HTTP

      headers; the event payload is the HTTP body). All requests carry

      `WebHook-Request-Origin: <instance>.webpubsub.azure.com` and a

      signed `ce-signature` header so the upstream can validate the

      origin of the request.

      '
    servers:
    - upstream
    bindings:
      http:
        bindingVersion: 0.3.0
        type: request
        method: POST
    subscribe:
      operationId: upstreamDeliver
      summary: 'Events delivered by Azure Web PubSub to the upstream webhook.

        `connect` and user events are *blocking* events whose response

        the service waits for; `connected` and `disconnected` are

        *unblocking* (asynchronous) notifications.

        '
      message:
        oneOf:
        - $ref: '#/components/messages/UpstreamSystemConnect'
        - $ref: '#/components/messages/UpstreamSystemConnected'
        - $ref: '#/components/messages/UpstreamSystemDisconnected'
        - $ref: '#/components/messages/UpstreamUserMessage'
        - $ref: '#/components/messages/UpstreamUserCustomEvent'
components:
  securitySchemes:
    clientAccessToken:
      type: httpApiKey
      in: query
      name: access_token
      description: 'Short-lived JWT access token passed as the `access_token` query

        parameter on the WebSocket handshake. Tokens are issued by the

        Web PubSub service data-plane REST API

        (`POST /api/hubs/{hub}/:generateToken`) or by a server SDK using

        the service AccessKey.

        '
  messages:
    JoinGroup:
      name: joinGroup
      title: Join Group request
      summary: Client asks the service to add the connection to a group.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/JoinGroupPayload'
    LeaveGroup:
      name: leaveGroup
      title: Leave Group request
      summary: Client asks the service to remove the connection from a group.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/LeaveGroupPayload'
    SendToGroup:
      name: sendToGroup
      title: Send-To-Group request
      summary: Client publishes a message to all connections in a group.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/SendToGroupPayload'
    SendEvent:
      name: event
      title: Send custom event request
      summary: 'Client sends a custom user event that the service forwards to

        the upstream event handler as a CloudEvents request with

        `ce-type: azure.webpubsub.user.<event_name>`.

        '
      contentType: application/json
      payload:
        $ref: '#/components/schemas/SendEventPayload'
    Ping:
      name: ping
      title: Ping
      summary: Client liveness check.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/PingPayload'
    SequenceAck:
      name: sequenceAck
      title: Sequence Ack (reliable subprotocol only)
      summary: 'Acknowledgement of a `sequenceId` delivered on an inbound

        message. Required for the `json.reliable.webpubsub.azure.v1`

        subprotocol so the service can release in-flight messages.

        '
      contentType: application/json
      payload:
        $ref: '#/components/schemas/SequenceAckPayload'
    AckResponse:
      name: ack
      title: Ack response
      summary: 'Service response to a client request that carried `ackId`.

        Clients should inspect `success` before reading `error`.

        '
      contentType: application/json
      payload:
        $ref: '#/components/schemas/AckResponsePayload'
    MessageFromGroup:
      name: messageFromGroup
      title: Group message
      summary: 'Data message delivered to the client because a publisher (REST

        API, server SDK, or another subprotocol client) sent it to a

        group the client has joined.

        '
      contentType: application/json
      payload:
        $ref: '#/components/schemas/MessageFromGroupPayload'
    MessageFromServer:
      name: messageFromServer
      title: Server message
      summary: 'Data message delivered to the client because the server (REST

        API or server SDK) targeted this connection, the user, or all

        connections.

        '
      contentType: application/json
      payload:
        $ref: '#/components/schemas/MessageFromServerPayload'
    SystemConnected:
      name: systemConnected
      title: System connected event
      summary: 'Service notifies the client that the WebSocket handshake

        succeeded. Reliable subprotocol additionally carries

        `reconnectionToken` for use on session recovery.

        '
      contentType: application/json
      payload:
        $ref: '#/components/schemas/SystemConnectedPayload'
    SystemDisconnected:
      name: systemDisconnected
      title: System disconnected event
      summary: 'Service notifies the client that the connection was closed by

        the server or declined by the service.

        '
      contentType: application/json
      payload:
        $ref: '#/components/schemas/SystemDisconnectedPayload'
    Pong:
      name: pong
      title: Pong
      summary: Service response to a `ping` request.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/PongPayload'
    UpstreamSystemConnect:
      name: upstreamSystemConnect
      title: Upstream `connect` (blocking)
      summary: 'Blocking CloudEvents request fired during WebSocket handshake.

        The upstream may approve the connection (HTTP 200 with optional

        `userId`/`groups`/`roles`/`subprotocol` body, or HTTP 204) or

        deny it (4xx). Used to perform authentication, authorization,

        subprotocol negotiation, and auto-join group assignment.

        '
      contentType: application/json
      bindings:
        http:
          bindingVersion: 0.3.0
          headers:
            $ref: '#/components/schemas/CloudEventsConnectHeaders'
      payload:
        $ref: '#/components/schemas/UpstreamConnectPayload'
    UpstreamSystemConnected:
      name: upstreamSystemConnected
      title: Upstream `connected` (unblocking)
      summary: 'Asynchronous notification fired after a client has successfully

        completed the WebSocket handshake. Upstream is expected to

        return a 2xx; non-2xx responses are logged by the service but

        do not affect the connection.

        '
      contentType: application/json
      bindings:
        http:
          bindingVersion: 0.3.0
          headers:
            $ref: '#/components/schemas/CloudEventsConnectedHeaders'
      payload:
        $ref: '#/components/schemas/UpstreamEmptyJsonPayload'
    UpstreamSystemDisconnected:
      name: upstreamSystemDisconnected
      title: Upstream `disconnected` (unblocking)
      summary: 'Asynchronous notification fired after a client disconnects, if

        the `connect` event previously returned a 2xx. The body carries

        the disconnect `reason`.

        '
      contentType: application/json
      bindings:
        http:
          bindingVersion: 0.3.0
          headers:
            $ref: '#/components/schemas/CloudEventsDisconnectedHeaders'
      payload:
        $ref: '#/components/schemas/UpstreamDisconnectedPayload'
    UpstreamUserMessage:
      name: upstreamUserMessage
      title: Upstream `message` for simple WebSocket clients (blocking)
      summary: 'Blocking CloudEvents request fired for every WebSocket frame a

        *simple* (no subprotocol) client sends. The HTTP body is the

        raw payload the client sent. The upstream''s response body, if

        any, is sent back to the client as a frame whose type follows

        the response `Content-Type` (`text/plain` => text frame,

        `application/octet-stream` => binary frame).

        '
      contentType: application/octet-stream
      bindings:
        http:
          bindingVersion: 0.3.0
          headers:
            $ref: '#/components/schemas/CloudEventsMessageHeaders'
      payload:
        $ref: '#/components/schemas/UpstreamUserMessagePayload'
    UpstreamUserCustomEvent:
      name: upstreamUserCustomEvent
      title: Upstream `<custom_event>` for PubSub clients (blocking)
      summary: 'Blocking CloudEvents request fired when a PubSub subprotocol

        client sends a `type: event` frame. The CloudEvents

        `ce-type` is `azure.webpubsub.user.<event_name>` and the body

        is the `data` field of the original frame (text, JSON, or

        binary, depending on `dataType`).

        '
      contentType: application/json
      bindings:
        http:
          bindingVersion: 0.3.0
          headers:
            $ref: '#/components/schemas/CloudEventsCustomEventHeaders'
      payload:
        $ref: '#/components/schemas/UpstreamUserCustomEventPayload'
  schemas:
    DataType:
      type: string
      enum:
      - json
      - text
      - binary
      description: 'Encoding for the `data` field. `json` accepts any JSON value;

        `text` requires a string; `binary` requires a base64-encoded

        string.

        '
    JoinGroupPayload:
      type: object
      required:
      - type
      - group
      properties:
        type:
          type: string
          const: joinGroup
        group:
          type: string
          description: Name of the group to join.
        ackId:
          type: integer
          format: int64
          description: 'Unique request identifier. If present, the service replies

            with an `ack` message carrying the same `ackId`.

            '
    LeaveGroupPayload:
      type: object
      required:
      - type
      - group
      properties:
        type:
          type: string
          const: leaveGroup
        group:
          type: string
          description: Name of the group to leave.
        ackId:
          type: integer
          format: int64
    SendToGroupPayload:
      type: object
      required:
      - type
      - group
      - data
      properties:
        type:
          type: string
          const: sendToGroup
        group:
          type: string
          description: Target group name.
        ackId:
          type: integer
          format: int64
        noEcho:
          type: boolean
          default: false
          description: 'If true, the publishing connection does not receive an echo

            of its own message.

            '
        dataType:
          $ref: '#/components/schemas/DataType'
        data:
          description: 'Payload to publish. Type depends on `dataType`: any JSON

            value for `json`, string for `text`, base64-encoded string

            for `binary`.

            '
    SendEventPayload:
      type: object
      required:
      - type
      - event
      - data
      properties:
        type:
          type: string
          const: event
        event:
          type: string
          description: 'Custom event name. The service forwards this to the

            upstream webhook with `ce-type: azure.webpubsub.user.<event>`

            and `ce-eventName: <event>`.

            '
        ackId:
          type: integer
          format: int64
        dataType:
          $ref: '#/components/schemas/DataType'
        data:
          description: 'Event payload. Type depends on `dataType`.

            '
    PingPayload:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          const: ping
    SequenceAckPayload:
      type: object
      required:
      - type
      - sequenceId
      properties:
        type:
          type: string
          const: sequenceAck
        sequenceId:
          type: integer
          format: int64
          description: 'Highest `sequenceId` the client has successfully processed

            from the service. Used by the reliable subprotocol so the

            service can release buffered messages.

            '
    AckResponsePayload:
      type: object
      required:
      - type
      - ackId
      - success
      properties:
        type:
          type: string
          const: ack
        ackId:
          type: integer
          format: int64
        success:
          type: boolean
        error:
          type: object
          description: Present when `success` is false.
          required:
          - name
          - message
          properties:
            name:
              type: string
              enum:
              - Forbidden
              - InternalServerError
              - Duplicate
            message:
              type: string
    MessageFromGroupPayload:
      type: object
      required:
      - type
      - from
      - group
      - data
      properties:
        sequenceId:
          type: integer
          format: int64
          description: 'Only present on the reliable subprotocol. Client must

            acknowledge using `sequenceAck`.

            '
        type:
          type: string
          const: message
        from:
          type: string
          const: group
        group:
          type: string
        dataType:
          $ref: '#/components/schemas/DataType'
        data:
          description: Message payload (encoding follows `dataType`).
        fromUserId:
          type: string
          description: User id of the publisher, if any.
    MessageFromServerPayload:
      type: object
      required:
      - type
      - from
      - data
      properties:
        sequenceId:
          type: integer
          format: int64
          description: Only present on the reliable subprotocol.
        type:
          type: string
          const: message
        from:
          type: string
          const: server
        dataType:
          $ref: '#/components/schemas/DataType'
        data:
          description: Message payload (encoding follows `dataType`).
    SystemConnectedPayload:
      type: object
      required:
      - type
      - event
      - connectionId
      properties:
        type:
          type: string
          const: system
        event:
          type: string
          const: connected
        userId:
          type: string
          description: Authenticated user id of the connection, if any.
        connectionId:
          type: string
          description: Service-assigned unique connection id.
        reconnectionToken:
          type: string
          description: 'Only present on the reliable subprotocol. Pass back as

            `awps_reconnection_token` (together with `awps_connection_id`)

            on a new connect request to recover this session.

            '
    SystemDisconnectedPayload:
      type: object
      required:
      - type
      - event
      properties:
        type:
          type: string
          const: system
        event:
          type: string
          const: disconnected
        message:
          type: string
          description: Human-readable disconnect reason.
    PongPayload:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          const: pong
    CloudEventsCommonHeaders:
      type: object
      description: 'Common CloudEvents 1.0 binary-mode HTTP headers attached to

        every upstream request from Web PubSub. Additional event-type

        specific headers are documented per message.

        '
      required:
      - ce-specversion
      - ce-type
      - ce-source
      - ce-id
      - ce-time
      - ce-signature
      - ce-connectionId
      - ce-hub
      - ce-eventName
      - WebHook-Request-Origin
      properties:
        WebHook-Request-Origin:
          type: string
          description: '`<instance>.webpubsub.azure.com`'
        ce-specversion:
          type: string
          const: '1.0'
        ce-type:
          type: string
          description: 'Event type. `azure.webpubsub.sys.<connect|connected|disconnected>`

            for system events; `azure.webpubsub.user.message` for simple

            WebSocket frames; `azure.webpubsub.user.<event_name>` for

            PubSub subprotocol custom events.

            '
        ce-source:
          type: string
          description: '`/hubs/{hub}/client/{connectionId}` (or `/client/{connectionId}`
            for custom events).'
        ce-id:
          type: string
          description: Unique event id.
        ce-time:
          type: string
          format: date-time
        ce-signature:
          type: string
          description: '`sha256={hash-primary},sha256={hash-secondary}` where each

            hash is `Hex(HMAC_SHA256(accessKey, connectionId))`.

            Upstream should validate before processing.

            '
        ce-userId:
          type: string
        ce-connectionId:
          type: string
        ce-hub:
          type: string
        ce-eventName:
          type: string
          description: Event name without the `azure.webpubsub.*` prefix.
        ce-subprotocol:
          type: string
          description: Negotiated subprotocol, if any.
        ce-connectionState:
          type: string
          description: 'Per-connection state propagated between events. Set by

            upstream on a previous blocking event response and echoed

            back on subsequent events.

            '
    CloudEventsConnectHeaders:
      allOf:
      - $ref: '#/components/schemas/CloudEventsCommonHeaders'
      - type: object
        properties:
          ce-type:
            type: string
            const: azure.webpubsub.sys.connect
          ce-eventName:
            type: string
            const: connect
    CloudEventsConnectedHeaders:
      allOf:
      - $ref: '#/components/schemas/CloudEventsCommonHeaders'
      - type: object
        properties:
          ce-type:
            type: string
            const: azure.webpubsub.sys.connected
          ce-eventName:
            type: string
            const: connected
    CloudEventsDisconnectedHeaders:
      allOf:
      - $ref: '#/components/schemas/CloudEventsCommonHeaders'
      - type: object
        properties:
          ce-type:
            type: string
            const: azure.webpubsub.sys.disconnected
          ce-eventName:
            type: string
            const: disconnected
    CloudEventsMessageHeaders:
      allOf:
      - $ref: '#/components/schemas/CloudEventsCommonHeaders'
      - type: object
        properties:
          ce-type:
            type: string
            const: azure.webpubsub.user.message
          ce-eventName:
            type: string
            const: message
    CloudEventsCustomEventHeaders:
      allOf:
      - $ref: '#/components/schemas/CloudEventsCommonHeaders'
      - type: object
        properties:
          ce-type:
            type: string
            description: '`azure.webpubsub.user.<event_name>`'
            pattern: ^azure\.webpubsub\.user\..+$
    UpstreamConnectPayload:
      type: object
      description: 'Body of the `connect` upstream request. Carries the client''s

        authentication context (claims), connect-time query string,

        request headers, requested subprotocols, and any client TLS

        certificates presented during the handshake.

        '
      properties:
        claims:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Claims parsed from the client's access token.
        query:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Query string parameters from the connect request.
        headers:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: HTTP request headers from the connect request.
        subprotocols:
          type: array
          items:
            type: string
          description: 'Subprotocols offered by the client in

            `Sec-WebSocket-Protocol`.

            '
        clientCertificates:
          type: array
          description: Client TLS certificates, if any.
          items:
            type: object
            properties:
              thumbprint:
                type: string
                description: SHA-1 thumbprint of the certificate.
              content:
                type: string
                description: PEM-encoded certificate content.
    UpstreamEmptyJsonPayload:
      type: object
      description: Empty JSON object. The `connected` event carries no body fields.
    UpstreamDisconnectedPayload:
      type: object
      required:
      - reason
      properties:
        reason:
          type: string
          description: Reason the client disconnected.
    UpstreamUserMessagePayload:
      description: 'Raw client frame contents. The HTTP `Content-Type` is

        `text/plain` for text frames and `application/octet-stream` for

        binary frames.

        '
      oneOf:
      - type: string
      - type: string
        format: binary
    UpstreamUserCustomEventPayload:
      description: 'The `data` value from the original `type: event` frame. The

        HTTP `Content-Type` reflects the original `dataType`:

        `text/plain` for `text`, `application/json` for `json`,

        `application/octet-stream` for `binary`.

        '
      oneOf:
      - type: string
      - type: object
        additionalProperties: true
      - type: array
        items: {}
      - type: number
      - type: boolean
      - type: 'null'
      - type: string
        format: binary
externalDocs:
  description: Azure Web PubSub overview
  url: https://learn.microsoft.com/en-us/azure/azure-web-pubsub/