asyncapi: 2.6.0
info:
  title: SASE Multitenant Notifications
  version: '1.0'
  description: >-
    Palo Alto Networks SASE (Secure Access Service Edge) delivers real-time
    notifications for security incidents, platform announcements, dataplane
    upgrades, and certificate expiration warnings across multitenant
    deployments. Notifications are sent as HTTP POST requests to registered
    webhook endpoints configured at the tenant or tenant service group (TSG)
    level. Each notification includes a tenant context identifier (tsg_id)
    for routing in multitenant environments. Notification subscriptions are
    managed through the SASE Multitenant Notification Service API, allowing
    administrators to select notification types, severity thresholds, and
    delivery endpoints for each tenant.
  contact:
    name: Palo Alto Networks Developer Support
    url: https://pan.dev/
  license:
    name: Proprietary
    url: https://www.paloaltonetworks.com/legal
servers:
  webhook:
    url: '{notificationEndpoint}'
    protocol: https
    description: >-
      Your notification endpoint URL registered with the SASE Multitenant
      Notification Service. Configure notification subscriptions via the
      SASE API to specify which notification types are delivered to this
      endpoint. The endpoint must accept POST requests with JSON payloads
      and return a 2xx response within 30 seconds.
    variables:
      notificationEndpoint:
        description: The URL of your registered notification endpoint.
channels:
  /notification/incident:
    description: >-
      Channel for security incident notifications. Triggered when SASE
      detects a security incident such as a policy breach, threat detection,
      or anomalous activity within a tenant's network perimeter. Incident
      notifications include severity classification, affected tenant
      context, and descriptive details for triage and response.
    subscribe:
      operationId: onIncidentNotification
      summary: Security incident notification
      message:
        $ref: '#/components/messages/IncidentNotification'
  /notification/announcement:
    description: >-
      Channel for platform announcement notifications. Delivered when
      Palo Alto Networks publishes service announcements including
      scheduled maintenance windows, feature releases, deprecation
      notices, and service status updates that affect SASE tenants.
    subscribe:
      operationId: onAnnouncementNotification
      summary: Platform announcement notification
      message:
        $ref: '#/components/messages/AnnouncementNotification'
  /notification/dataplane-upgrade:
    description: >-
      Channel for dataplane upgrade notifications. Triggered when a SASE
      dataplane upgrade is scheduled, in progress, or completed for a
      specific region. Notifications include the current and target software
      versions, scheduled maintenance window, and upgrade status transitions.
    subscribe:
      operationId: onDataplaneUpgradeNotification
      summary: Dataplane upgrade notification
      message:
        $ref: '#/components/messages/DataplaneUpgradeNotification'
  /notification/certificate-expiry:
    description: >-
      Channel for certificate expiration warning notifications. Triggered
      when TLS/SSL certificates used by SASE service connections, GlobalProtect
      portals, or custom domains are approaching their expiration date.
      Warnings are sent at configurable intervals (e.g., 90, 60, 30, 14, 7
      days before expiry) to allow administrators to renew certificates
      before service disruption.
    subscribe:
      operationId: onCertificateExpiryNotification
      summary: Certificate expiration warning notification
      message:
        $ref: '#/components/messages/CertificateExpiryNotification'
components:
  messages:
    IncidentNotification:
      name: IncidentNotification
      title: SASE Security Incident Notification
      summary: >-
        Webhook payload sent when a security incident is detected within a
        SASE tenant. Contains the incident classification, severity, affected
        tenant context, and descriptive information for triage.
      contentType: application/json
      payload:
        type: object
        properties:
          notificationId:
            type: string
            description: Unique identifier for this notification delivery.
            example: '794757'
          type:
            type: string
            enum:
            - incident
            description: Notification type identifier.
            example: incident
          tsg_id:
            type: string
            description: >-
              Tenant Service Group identifier indicating which tenant
              context the incident belongs to.
            example: '912769'
          severity:
            type: string
            enum:
            - informational
            - low
            - medium
            - high
            - critical
            description: Severity classification of the security incident.
            example: medium
          title:
            type: string
            description: Brief title summarizing the incident.
            example: Production Agent 89
          description:
            type: string
            description: >-
              Detailed description of the incident including affected
              resources, detection context, and recommended actions.
            example: Activity malware threat Security blocked configured network traffic alert activity.
          timestamp:
            type: string
            format: date-time
            description: Timestamp when the incident was detected.
            example: '2024-07-20T06:56:43Z'
          category:
            type: string
            description: >-
              Incident category such as threat, policy_violation, anomaly,
              or data_loss.
            example: standard
          affectedResources:
            type: array
            description: List of resources affected by the incident.
            items:
              type: object
              properties:
                resourceType:
                  type: string
                  description: Type of affected resource.
                  example: custom
                resourceId:
                  type: string
                  description: Identifier of the affected resource.
                  example: '991933'
            example:
            - resourceType: advanced
              resourceId: '274661'
            - resourceType: standard
              resourceId: '513811'
          callbackUrl:
            type: string
            format: uri
            description: Direct link to the incident in the SASE management console.
            example: https://portal.example.com/087340
      examples:
      - name: IncidentNotificationDefaultExample
        summary: Default IncidentNotification example payload
        x-microcks-default: true
        payload:
          notificationId: '869591'
          type: incident
          tsg_id: '714248'
          severity: low
          title: Staging Gateway 01
          description: Applied incident network malware Security investigation malware monitoring malware firewall.
          timestamp: '2026-02-01T00:03:22Z'
          category: advanced
          affectedResources:
          - resourceType: custom
            resourceId: '626533'
          callbackUrl: https://portal.example.com/7f3823
    AnnouncementNotification:
      name: AnnouncementNotification
      title: SASE Platform Announcement Notification
      summary: >-
        Webhook payload sent for platform announcements including maintenance
        windows, feature releases, deprecation notices, and service status
        updates.
      contentType: application/json
      payload:
        type: object
        properties:
          notificationId:
            type: string
            description: Unique identifier for this notification delivery.
            example: '120038'
          type:
            type: string
            enum:
            - announcement
            description: Notification type identifier.
            example: announcement
          title:
            type: string
            description: Announcement title.
            example: Branch Agent 43
          body:
            type: string
            description: >-
              Full announcement body with details about the platform change,
              maintenance window, or service update.
            example: example-body
          category:
            type: string
            enum:
            - maintenance
            - feature_release
            - deprecation
            - service_status
            - security_advisory
            description: Category of the announcement.
            example: maintenance
          affectedServices:
            type: array
            description: >-
              List of SASE services affected by the announcement, such as
              Prisma Access, GlobalProtect, ADEM, SWG, or ZTNA.
            items:
              type: string
            example:
            - example-affectedServices_item
            - example-affectedServices_item
          effectiveDate:
            type: string
            format: date-time
            description: >-
              Date and time when the announced change takes effect.
            example: '2024-08-26T11:19:41Z'
          timestamp:
            type: string
            format: date-time
            description: Timestamp when the announcement was published.
            example: '2025-05-20T21:35:18Z'
          tsg_id:
            type: string
            description: >-
              Tenant Service Group identifier if the announcement is
              tenant-specific. Omitted for global announcements.
            example: '610576'
      examples:
      - name: AnnouncementNotificationDefaultExample
        summary: Default AnnouncementNotification example payload
        x-microcks-default: true
        payload:
          notificationId: '844637'
          type: announcement
          title: Production Agent 06
          body: example-body
          category: maintenance
          affectedServices:
          - example-affectedServices_item
          effectiveDate: '2024-10-27T22:08:12Z'
          timestamp: '2026-04-21T09:59:11Z'
          tsg_id: '211008'
    DataplaneUpgradeNotification:
      name: DataplaneUpgradeNotification
      title: SASE Dataplane Upgrade Notification
      summary: >-
        Webhook payload sent when a SASE dataplane upgrade is scheduled,
        in progress, or completed for a region.
      contentType: application/json
      payload:
        type: object
        properties:
          notificationId:
            type: string
            description: Unique identifier for this notification delivery.
            example: '769945'
          type:
            type: string
            enum:
            - dataplane_upgrade
            description: Notification type identifier.
            example: dataplane_upgrade
          tsg_id:
            type: string
            description: Tenant Service Group identifier for the affected tenant.
            example: '320093'
          region:
            type: string
            description: >-
              SASE compute region where the dataplane upgrade is occurring,
              such as us-east-1, eu-west-1, or ap-southeast-1.
            example: us-east-1
          currentVersion:
            type: string
            description: >-
              Current dataplane software version before the upgrade.
            example: 3.6.9
          targetVersion:
            type: string
            description: >-
              Target dataplane software version after the upgrade completes.
            example: 7.4.8
          scheduledTime:
            type: string
            format: date-time
            description: >-
              Scheduled start time for the dataplane upgrade maintenance
              window.
            example: '2026-01-25T00:46:59Z'
          estimatedEndTime:
            type: string
            format: date-time
            description: >-
              Estimated end time for the dataplane upgrade maintenance window.
            example: '2024-06-27T02:44:04Z'
          status:
            type: string
            enum:
            - scheduled
            - in_progress
            - completed
            - failed
            - rolled_back
            description: Current status of the dataplane upgrade.
            example: rolled_back
          timestamp:
            type: string
            format: date-time
            description: Timestamp when this notification was generated.
            example: '2026-01-16T03:28:54Z'
      examples:
      - name: DataplaneUpgradeNotificationDefaultExample
        summary: Default DataplaneUpgradeNotification example payload
        x-microcks-default: true
        payload:
          notificationId: '328452'
          type: dataplane_upgrade
          tsg_id: '786196'
          region: us-west-2
          currentVersion: 1.3.2
          targetVersion: 6.7.5
          scheduledTime: '2024-04-13T16:54:37Z'
          estimatedEndTime: '2024-05-12T01:15:45Z'
          status: in_progress
          timestamp: '2026-02-13T04:24:11Z'
    CertificateExpiryNotification:
      name: CertificateExpiryNotification
      title: Certificate Expiration Warning Notification
      summary: >-
        Webhook payload sent when a TLS/SSL certificate used by SASE services
        is approaching its expiration date.
      contentType: application/json
      payload:
        type: object
        properties:
          notificationId:
            type: string
            description: Unique identifier for this notification delivery.
            example: '619771'
          type:
            type: string
            enum:
            - certificate_expiry
            description: Notification type identifier.
            example: certificate_expiry
          tsg_id:
            type: string
            description: Tenant Service Group identifier for the affected tenant.
            example: '822011'
          certificateName:
            type: string
            description: Name of the certificate approaching expiration.
            example: Primary Policy 24
          serialNumber:
            type: string
            description: Certificate serial number.
            example: example-serialNumber
          issuer:
            type: string
            description: Certificate issuer distinguished name.
            example: example-issuer
          subject:
            type: string
            description: Certificate subject distinguished name.
            example: example-subject
          expirationDate:
            type: string
            format: date-time
            description: Certificate expiration date and time.
            example: '2026-04-24T03:06:26Z'
          daysUntilExpiry:
            type: integer
            description: Number of days remaining until the certificate expires.
            example: 743
          usedBy:
            type: array
            description: >-
              List of SASE services or configurations using this certificate.
            items:
              type: string
            example:
            - example-usedBy_item
          timestamp:
            type: string
            format: date-time
            description: Timestamp when this notification was generated.
            example: '2026-06-26T05:21:54Z'
      examples:
      - name: CertificateExpiryNotificationDefaultExample
        summary: Default CertificateExpiryNotification example payload
        x-microcks-default: true
        payload:
          notificationId: '100470'
          type: certificate_expiry
          tsg_id: '798044'
          certificateName: Production Policy 42
          serialNumber: example-serialNumber
          issuer: example-issuer
          subject: example-subject
          expirationDate: '2024-10-16T09:06:17Z'
          daysUntilExpiry: 995
          usedBy:
          - example-usedBy_item
          timestamp: '2026-06-06T22:23:29Z'
  schemas:
    IncidentDetail:
      type: object
      description: >-
        Detailed information about a SASE security incident for enrichment
        and correlation.
      properties:
        incidentId:
          type: string
          description: Unique incident identifier.
          example: '241159'
        type:
          type: string
          description: Incident type classification.
          example: advanced
        severity:
          type: string
          enum:
          - informational
          - low
          - medium
          - high
          - critical
          example: low
        title:
          type: string
          description: Incident title.
          example: Corporate Policy 57
        description:
          type: string
          description: Incident description.
          example: Alert alert rule incident violation violation endpoint.
        tsg_id:
          type: string
          description: Tenant Service Group identifier.
          example: '794912'
        category:
          type: string
          description: Incident category.
          example: standard
        detectionSource:
          type: string
          description: Source of the incident detection.
          example: example-detectionSource
        timestamp:
          type: string
          format: date-time
          example: '2026-11-26T07:09:03Z'
    ServiceInfo:
      type: object
      description: >-
        Information about a SASE service affected by a notification.
      properties:
        serviceName:
          type: string
          description: Name of the SASE service.
          example: Corporate Agent 77
        serviceStatus:
          type: string
          enum:
          - operational
          - degraded
          - maintenance
          - outage
          description: Current operational status of the service.
          example: degraded
        region:
          type: string
          description: Region where the service is deployed.
          example: us-west-2
    TenantContext:
      type: object
      description: >-
        Tenant context information for multitenant notification routing.
      properties:
        tsg_id:
          type: string
          description: Tenant Service Group identifier.
          example: '560610'
        tenantName:
          type: string
          description: Human-readable tenant name.
          example: Staging Sensor 21
        parentTsgId:
          type: string
          description: >-
            Parent Tenant Service Group identifier for hierarchical
            tenant structures.
          example: '498954'