asyncapi: 2.6.0
info:
  title: Prisma Cloud CSPM Webhooks
  version: 1.0.0
  description: >
    Prisma Cloud Cloud Security Posture Management (CSPM) Webhooks deliver
    real-time event notifications for policy violations and security alerts
    across multi-cloud environments including AWS, Azure, GCP, OCI, and
    Alibaba Cloud. Webhooks are configured as notification channels in Prisma
    Cloud Settings > Integrations and dispatch HTTP POST requests with JSON
    payloads to registered HTTPS endpoints whenever alert lifecycle events
    occur. Supported events include alert creation, update, resolution, and
    dismissal. Webhooks enable integration with SIEM platforms, SOAR systems,
    ticketing tools, and custom security automation workflows.
  contact:
    name: Palo Alto Networks Developer Support
    url: https://pan.dev/
    email: support@paloaltonetworks.com
  license:
    name: Proprietary
    url: https://www.paloaltonetworks.com/legal

servers:
  customer-webhook:
    url: '{webhookUrl}'
    protocol: https
    description: >
      Customer-configured HTTPS endpoint to receive Prisma Cloud webhook
      notifications. The endpoint must be publicly accessible, accept HTTP
      POST requests with a JSON body, and return a 2xx HTTP status code.
      Configure the endpoint URL in Prisma Cloud Settings > Integrations >
      Add Integration > Webhook.
    variables:
      webhookUrl:
        description: >
          The fully-qualified HTTPS URL of the customer's webhook receiver
          endpoint, as configured in the Prisma Cloud integration settings.
    security:
    - webhookSecret: []

tags:
- name: alerts
  description: Prisma Cloud CSPM security alert lifecycle events
- name: policy
  description: Cloud security policy violation notifications
- name: webhooks
  description: Outbound webhook event delivery to customer endpoints
- name: cspm
  description: Cloud Security Posture Management events

defaultContentType: application/json

channels:
  alert/created:
    description: >
      Triggered when Prisma Cloud generates a new alert due to a policy
      violation detected during a cloud resource scan. The alert payload
      contains full context about the violated policy, the affected cloud
      resource, and its account.
    subscribe:
      operationId: onAlertCreated
      summary: New policy-violation alert created
      description: >
        Fired when a new Prisma Cloud CSPM alert is created. This event
        signals that a cloud resource has been found to violate a configured
        security policy. The notification_type field will be alert.created.
      message:
        $ref: '#/components/messages/AlertCreated'
      bindings:
        http:
          method: POST

  alert/updated:
    description: >
      Triggered when an existing Prisma Cloud alert is updated, typically
      when the underlying resource configuration changes after the initial
      policy violation was detected, causing a re-evaluation.
    subscribe:
      operationId: onAlertUpdated
      summary: Existing alert updated
      description: >
        Fired when an alert's metadata or associated resource state changes.
        The notification_type field will be alert.updated.
      message:
        $ref: '#/components/messages/AlertUpdated'
      bindings:
        http:
          method: POST

  alert/resolved:
    description: >
      Triggered when a Prisma Cloud alert is automatically resolved because
      the underlying cloud resource configuration has been brought back into
      compliance with the policy.
    subscribe:
      operationId: onAlertResolved
      summary: Alert automatically resolved
      description: >
        Fired when the cloud resource that triggered the alert has been
        remediated and the policy violation no longer applies. The
        notification_type field will be alert.resolved.
      message:
        $ref: '#/components/messages/AlertResolved'
      bindings:
        http:
          method: POST

  alert/dismissed:
    description: >
      Triggered when a Prisma Cloud alert is manually dismissed by a user
      or suppressed by a configured snooze or suppression rule.
    subscribe:
      operationId: onAlertDismissed
      summary: Alert manually dismissed or snoozed
      description: >
        Fired when a user explicitly dismisses an alert or when an alert
        matches a suppression rule. The notification_type field will be
        alert.dismissed.
      message:
        $ref: '#/components/messages/AlertDismissed'
      bindings:
        http:
          method: POST

components:
  messages:
    AlertCreated:
      name: AlertCreated
      title: Alert Created
      summary: A new Prisma Cloud policy-violation alert has been created
      contentType: application/json
      payload:
        $ref: '#/components/schemas/AlertPayload'
      examples:
      - name: S3BucketPublicAlertCreated
        summary: New alert for a publicly accessible AWS S3 bucket
        payload:
          notification_type: alert.created
          alert_id: P-12345678
          alert_status: open
          policy_id: a6b45001-e4af-4b52-ac58-9234a68ef123
          policy_name: AWS S3 Bucket Publicly Accessible
          cloud_type: aws
          account_id: '123456789012'
          resource_id: arn:aws:s3:::my-public-bucket
          resource_type: s3
          severity: high
          timestamp: '2024-01-15T10:30:00.000Z'

        x-microcks-default: true
    AlertUpdated:
      name: AlertUpdated
      title: Alert Updated
      summary: An existing Prisma Cloud policy-violation alert has been updated
      contentType: application/json
      payload:
        $ref: '#/components/schemas/AlertPayload'
      examples:
      - name: S3BucketAlertUpdated
        summary: Updated alert after resource configuration change
        payload:
          notification_type: alert.updated
          alert_id: P-12345678
          alert_status: open
          policy_id: a6b45001-e4af-4b52-ac58-9234a68ef123
          policy_name: AWS S3 Bucket Publicly Accessible
          cloud_type: aws
          account_id: '123456789012'
          resource_id: arn:aws:s3:::my-public-bucket
          resource_type: s3
          severity: high
          timestamp: '2024-01-15T11:00:00.000Z'

        x-microcks-default: true
    AlertResolved:
      name: AlertResolved
      title: Alert Resolved
      summary: A Prisma Cloud policy-violation alert has been automatically resolved
      contentType: application/json
      payload:
        $ref: '#/components/schemas/AlertPayload'
      examples:
      - name: S3BucketAlertResolved
        summary: Alert resolved after S3 bucket was made private
        payload:
          notification_type: alert.resolved
          alert_id: P-12345678
          alert_status: resolved
          policy_id: a6b45001-e4af-4b52-ac58-9234a68ef123
          policy_name: AWS S3 Bucket Publicly Accessible
          cloud_type: aws
          account_id: '123456789012'
          resource_id: arn:aws:s3:::my-public-bucket
          resource_type: s3
          severity: high
          timestamp: '2024-01-15T12:00:00.000Z'

        x-microcks-default: true
    AlertDismissed:
      name: AlertDismissed
      title: Alert Dismissed
      summary: A Prisma Cloud policy-violation alert has been dismissed
      contentType: application/json
      payload:
        $ref: '#/components/schemas/AlertPayload'
      examples:
      - name: S3BucketAlertDismissed
        summary: Alert dismissed by security team with a reason note
        payload:
          notification_type: alert.dismissed
          alert_id: P-12345678
          alert_status: dismissed
          policy_id: a6b45001-e4af-4b52-ac58-9234a68ef123
          policy_name: AWS S3 Bucket Publicly Accessible
          cloud_type: aws
          account_id: '123456789012'
          resource_id: arn:aws:s3:::my-public-bucket
          resource_type: s3
          severity: high
          timestamp: '2024-01-15T13:00:00.000Z'

        x-microcks-default: true
  schemas:
    AlertPayload:
      type: object
      description: >
        The payload delivered to the webhook endpoint for every Prisma Cloud
        CSPM alert lifecycle event. Contains all contextual information about
        the event type, the alert, the violated policy, and the affected cloud
        resource.
      required:
      - notification_type
      - alert_id
      - alert_status
      - policy_id
      - policy_name
      - cloud_type
      - account_id
      - resource_id
      - resource_type
      - severity
      - timestamp
      properties:
        notification_type:
          type: string
          description: >
            The type of alert lifecycle event that triggered this webhook
            notification. Identifies whether this is a creation, update,
            resolution, or dismissal event.
          enum:
          - alert.created
          - alert.updated
          - alert.resolved
          - alert.dismissed
          example: alert.created
        alert_id:
          type: string
          description: >
            The unique identifier for the Prisma Cloud alert. Alert IDs are
            prefixed with 'P-' followed by a numeric sequence, used to
            reference the alert in Prisma Cloud API operations and the
            management console.
          example: P-12345678
        alert_status:
          type: string
          description: >
            The current lifecycle status of the alert at the time this
            webhook notification was dispatched.
          enum:
          - open
          - resolved
          - dismissed
          - snoozed
          example: open
        policy_id:
          type: string
          format: uuid
          description: >
            The unique UUID identifier of the Prisma Cloud security policy
            that was violated and triggered this alert. Can be used to
            retrieve full policy details via the Prisma Cloud API.
          example: a6b45001-e4af-4b52-ac58-9234a68ef123
        policy_name:
          type: string
          description: >
            The human-readable display name of the Prisma Cloud security
            policy that was violated. Provides immediate context about the
            nature of the misconfiguration or compliance gap detected.
          example: AWS S3 Bucket Publicly Accessible
        cloud_type:
          type: string
          description: >
            The cloud service provider where the violating resource resides.
            Identifies which cloud environment requires investigation and
            remediation.
          enum:
          - aws
          - azure
          - gcp
          - oci
          - alibaba_cloud
          example: aws
        account_id:
          type: string
          description: >
            The cloud provider account ID, subscription ID, or project ID
            where the violating resource is deployed. Used to identify the
            specific cloud account requiring remediation.
          example: '123456789012'
        resource_id:
          type: string
          description: >
            The unique identifier of the cloud resource that violated the
            policy. For AWS resources this is typically an ARN. For Azure
            resources this is the resource ID path. For GCP resources this
            is the full resource name.
          example: arn:aws:s3:::my-public-bucket
        resource_type:
          type: string
          description: >
            The cloud provider service or resource type of the violating
            resource (e.g., s3, ec2, azure_storage_account,
            google_storage_bucket). Used to identify the type of
            infrastructure requiring remediation.
          example: s3
        severity:
          type: string
          description: >
            The severity level of the policy violation as defined by the
            Prisma Cloud security policy. Drives alert prioritization and
            notification routing in downstream systems.
          enum:
          - informational
          - low
          - medium
          - high
          - critical
          example: high
        timestamp:
          type: string
          format: date-time
          description: >
            The ISO 8601 date-time string indicating when this alert event
            occurred. For created events this is the alert creation time.
            For resolved or dismissed events this is the time of the
            status change.
          example: '2024-01-15T10:30:00.000Z'

  securitySchemes:
    webhookSecret:
      type: httpApiKey
      description: >
        An optional shared secret token configured in Prisma Cloud that is
        included in the X-Redlock-Auth HTTP header of each webhook request.
        Recipients should validate this header value to verify that payloads
        originate from Prisma Cloud and have not been tampered with.
      name: X-Redlock-Auth
      in: header