Juniper Mist Webhooks

asyncapi: 2.6.0
info:
  title: Juniper Mist Webhooks
  version: '1.0'
  description: >-
    Juniper Mist delivers real-time webhook notifications for network events,
    device state changes, alarms, audits, and client activity. Webhooks are
    configured at the organization or site level through the Mist dashboard
    or API. When events occur, Mist sends HTTP POST requests with JSON
    payloads to registered webhook URLs. Webhook topics include device
    events, alarms, audits, client sessions, location updates, zone
    occupancy, asset tracking, and network anomalies detected by the
    Marvis AI engine. Each webhook delivery includes a topic header and
    a payload containing one or more events. Failed deliveries are retried
    with exponential backoff.
  contact:
    name: Juniper Mist Developer Support
    url: https://www.juniper.net/documentation/product/us/en/mist/
  license:
    name: Proprietary
    url: https://www.juniper.net/us/en/legal-notices.html
servers:
  webhook:
    url: '{webhookUrl}'
    protocol: https
    description: >-
      Your webhook endpoint URL registered in the Mist dashboard under
      Organization > Settings > Webhooks or via the API. The endpoint
      must accept POST requests with JSON payloads and return a 2xx
      status code within 30 seconds.
    variables:
      webhookUrl:
        description: The URL of your registered webhook endpoint.
channels:
  /device-events:
    description: >-
      Channel for device state change events. Triggered when access points,
      switches, or gateways come online, go offline, or experience
      configuration changes. Includes AP restarts, firmware upgrades,
      and connectivity state transitions.
    subscribe:
      operationId: onDeviceEvents
      summary: Device event notifications
      message:
        $ref: '#/components/messages/DeviceEventMessage'
  /alarms:
    description: >-
      Channel for alarm notifications. Triggered when new alarms are
      raised or existing alarms are cleared. Alarm types include device
      health, connectivity, configuration, capacity, and security events.
    subscribe:
      operationId: onAlarms
      summary: Alarm notifications
      message:
        $ref: '#/components/messages/AlarmMessage'
  /audits:
    description: >-
      Channel for audit log notifications. Triggered when administrative
      actions are performed such as configuration changes, user logins,
      device operations, and policy updates.
    subscribe:
      operationId: onAudits
      summary: Audit log notifications
      message:
        $ref: '#/components/messages/AuditMessage'
  /client-sessions:
    description: >-
      Channel for wireless client session events. Triggered when clients
      connect, disconnect, or roam between access points. Includes
      session duration, data usage, and connection quality metrics.
    subscribe:
      operationId: onClientSessions
      summary: Client session notifications
      message:
        $ref: '#/components/messages/ClientSessionMessage'
  /location:
    description: >-
      Channel for location update events from Mist indoor positioning.
      Triggered when SDK clients or BLE asset tags are detected and their
      location is calculated using the Mist vBLE antenna array. Provides
      X/Y coordinates on the floor plan map.
    subscribe:
      operationId: onLocation
      summary: Location update notifications
      message:
        $ref: '#/components/messages/LocationMessage'
  /zone:
    description: >-
      Channel for zone occupancy events. Triggered when clients enter or
      exit defined proximity zones on the floor plan. Zones enable
      location-aware engagement and occupancy analytics.
    subscribe:
      operationId: onZone
      summary: Zone occupancy notifications
      message:
        $ref: '#/components/messages/ZoneMessage'
  /asset-raw:
    description: >-
      Channel for raw BLE asset tracking events. Triggered when BLE
      asset beacons are detected by Mist access points. Provides
      RSSI readings from multiple APs for real-time asset location.
    subscribe:
      operationId: onAssetRaw
      summary: BLE asset tracking notifications
      message:
        $ref: '#/components/messages/AssetRawMessage'
components:
  messages:
    DeviceEventMessage:
      name: DeviceEventMessage
      title: Device Event Webhook
      summary: >-
        Webhook payload for device state change events including AP, switch,
        and gateway online/offline transitions, reboots, and upgrades.
      contentType: application/json
      payload:
        type: object
        properties:
          topic:
            type: string
            const: device-events
            description: Webhook topic identifier.
          events:
            type: array
            items:
              type: object
              properties:
                org_id:
                  type: string
                  format: uuid
                  description: Organization ID.
                site_id:
                  type: string
                  format: uuid
                  description: Site ID.
                device_id:
                  type: string
                  format: uuid
                  description: Device ID.
                device_name:
                  type: string
                  description: Device name.
                device_type:
                  type: string
                  enum:
                    - ap
                    - switch
                    - gateway
                  description: Device type.
                mac:
                  type: string
                  description: Device MAC address.
                type:
                  type: string
                  description: >-
                    Event type (e.g., AP_CONNECTED, AP_DISCONNECTED,
                    AP_RESTARTED, AP_UPGRADED, SW_CONNECTED, GW_CONNECTED).
                text:
                  type: string
                  description: Human-readable event description.
                timestamp:
                  type: number
                  description: Event timestamp in epoch seconds.
    AlarmMessage:
      name: AlarmMessage
      title: Alarm Webhook
      summary: >-
        Webhook payload for alarm raise and clear events including device
        health, connectivity, and capacity alerts.
      contentType: application/json
      payload:
        type: object
        properties:
          topic:
            type: string
            const: alarms
            description: Webhook topic identifier.
          events:
            type: array
            items:
              type: object
              properties:
                org_id:
                  type: string
                  format: uuid
                site_id:
                  type: string
                  format: uuid
                alarm_id:
                  type: string
                  format: uuid
                  description: Alarm unique identifier.
                type:
                  type: string
                  description: Alarm type identifier.
                severity:
                  type: string
                  enum:
                    - critical
                    - warn
                    - info
                  description: Alarm severity.
                group:
                  type: string
                  description: Alarm group category.
                count:
                  type: integer
                  description: Occurrence count.
                cleared:
                  type: boolean
                  description: Whether the alarm has been cleared.
                timestamp:
                  type: number
                  description: Event timestamp in epoch seconds.
    AuditMessage:
      name: AuditMessage
      title: Audit Log Webhook
      summary: >-
        Webhook payload for administrative audit events including
        configuration changes and user actions.
      contentType: application/json
      payload:
        type: object
        properties:
          topic:
            type: string
            const: audits
            description: Webhook topic identifier.
          events:
            type: array
            items:
              type: object
              properties:
                org_id:
                  type: string
                  format: uuid
                site_id:
                  type: string
                  format: uuid
                admin_name:
                  type: string
                  description: Name of the administrator who performed the action.
                message:
                  type: string
                  description: Description of the action performed.
                src_ip:
                  type: string
                  description: Source IP address of the admin session.
                timestamp:
                  type: number
                  description: Event timestamp in epoch seconds.
    ClientSessionMessage:
      name: ClientSessionMessage
      title: Client Session Webhook
      summary: >-
        Webhook payload for wireless client connect, disconnect, and
        roam events with session metrics.
      contentType: application/json
      payload:
        type: object
        properties:
          topic:
            type: string
            const: client-sessions
            description: Webhook topic identifier.
          events:
            type: array
            items:
              type: object
              properties:
                org_id:
                  type: string
                  format: uuid
                site_id:
                  type: string
                  format: uuid
                ap:
                  type: string
                  description: AP MAC address.
                mac:
                  type: string
                  description: Client MAC address.
                ssid:
                  type: string
                  description: Connected SSID.
                connect:
                  type: number
                  description: Session start timestamp.
                disconnect:
                  type: number
                  description: Session end timestamp (0 if still connected).
                duration:
                  type: number
                  description: Session duration in seconds.
                rx_bytes:
                  type: integer
                  description: Bytes received during session.
                tx_bytes:
                  type: integer
                  description: Bytes transmitted during session.
                rssi:
                  type: number
                  description: Average RSSI during session.
                band:
                  type: string
                  description: Radio band.
                channel:
                  type: integer
                  description: Radio channel.
                wlan_id:
                  type: string
                  format: uuid
                  description: WLAN configuration ID.
                timestamp:
                  type: number
                  description: Event timestamp in epoch seconds.
    LocationMessage:
      name: LocationMessage
      title: Location Update Webhook
      summary: >-
        Webhook payload for indoor location position updates calculated
        by the Mist vBLE location engine.
      contentType: application/json
      payload:
        type: object
        properties:
          topic:
            type: string
            const: location
            description: Webhook topic identifier.
          events:
            type: array
            items:
              type: object
              properties:
                site_id:
                  type: string
                  format: uuid
                map_id:
                  type: string
                  format: uuid
                  description: Floor plan map ID.
                mac:
                  type: string
                  description: Client or asset MAC address.
                x:
                  type: number
                  description: X coordinate in meters from map origin.
                'y':
                  type: number
                  description: Y coordinate in meters from map origin.
                timestamp:
                  type: number
                  description: Location calculation timestamp.
    ZoneMessage:
      name: ZoneMessage
      title: Zone Occupancy Webhook
      summary: >-
        Webhook payload for proximity zone enter and exit events.
      contentType: application/json
      payload:
        type: object
        properties:
          topic:
            type: string
            const: zone
            description: Webhook topic identifier.
          events:
            type: array
            items:
              type: object
              properties:
                site_id:
                  type: string
                  format: uuid
                map_id:
                  type: string
                  format: uuid
                zone_id:
                  type: string
                  format: uuid
                  description: Proximity zone ID.
                mac:
                  type: string
                  description: Client or asset MAC address.
                trigger:
                  type: string
                  enum:
                    - enter
                    - exit
                  description: Zone transition direction.
                timestamp:
                  type: number
                  description: Event timestamp.
    AssetRawMessage:
      name: AssetRawMessage
      title: BLE Asset Raw Webhook
      summary: >-
        Webhook payload for raw BLE beacon detection events from access
        points used for asset tracking.
      contentType: application/json
      payload:
        type: object
        properties:
          topic:
            type: string
            const: asset-raw
            description: Webhook topic identifier.
          events:
            type: array
            items:
              type: object
              properties:
                site_id:
                  type: string
                  format: uuid
                mac:
                  type: string
                  description: BLE beacon MAC address.
                beam:
                  type: integer
                  description: vBLE antenna beam index.
                rssi:
                  type: number
                  description: Received signal strength in dBm.
                ap_mac:
                  type: string
                  description: Detecting AP MAC address.
                ibeacon_uuid:
                  type: string
                  description: iBeacon UUID if applicable.
                ibeacon_major:
                  type: integer
                  description: iBeacon major value.
                ibeacon_minor:
                  type: integer
                  description: iBeacon minor value.
                eddystone_uid_instance:
                  type: string
                  description: Eddystone UID instance ID if applicable.
                eddystone_uid_namespace:
                  type: string
                  description: Eddystone UID namespace if applicable.
                timestamp:
                  type: number