Cortex XDR Webhooks

asyncapi: 2.6.0
info:
  title: Cortex XDR Webhooks
  version: 1.0.0
  description: >
    Cortex XDR Webhooks provide real-time incident and alert notifications
    for security events detected across endpoints, networks, and cloud
    workloads. Webhooks are configured in Cortex XDR Settings >
    Notifications > External Applications and deliver HTTP POST requests
    with JSON payloads to registered HTTPS endpoints whenever incident and
    alert lifecycle events occur. Events include incident creation, status
    changes, severity changes, and new alert generation. Webhook
    notifications enable integration with SOAR platforms, ticketing systems,
    and custom automation workflows for accelerated incident response.
  contact:
    name: Palo Alto Networks Developer Support
    url: https://pan.dev/
    email: [email protected]
  license:
    name: Proprietary
    url: https://www.paloaltonetworks.com/legal

servers:
  customer-webhook:
    url: '{webhookUrl}'
    protocol: https
    description: >
      Customer-configured HTTPS endpoint to receive Cortex XDR webhook
      notifications. The endpoint must accept POST requests with JSON
      payloads and return a 2xx HTTP response. Configure the webhook URL
      in Cortex XDR Settings > Notifications > External Applications and
      assign it to one or more notification profiles.
    variables:
      webhookUrl:
        description: >
          The fully-qualified HTTPS URL of the customer's webhook receiver
          endpoint, as configured in the Cortex XDR notification settings.
    security:
    - hmacSignature: []

tags:
- name: incidents
  description: Cortex XDR security incident lifecycle events
- name: alerts
  description: Cortex XDR detection alert events
- name: webhooks
  description: Outbound webhook event delivery to customer endpoints
- name: xdr
  description: Extended Detection and Response platform events

defaultContentType: application/json

channels:
  incident/created:
    description: >
      Triggered when a new incident is created in Cortex XDR. Incidents are
      automatically created by correlating one or more related alerts that
      share common attributes such as affected endpoints, users, or attack
      patterns. This event signals the beginning of a new investigation
      context.
    subscribe:
      operationId: onIncidentCreated
      summary: New incident created
      description: >
        Fired when Cortex XDR creates a new incident by correlating related
        alerts into a unified attack story. The payload contains the incident
        identifier, name, creation time, initial severity, alert count, and
        assigned user information.
      message:
        $ref: '#/components/messages/IncidentCreated'
      bindings:
        http:
          method: POST

  incident/status_changed:
    description: >
      Triggered when an existing incident's investigation status changes.
      Status transitions include moving from new to under_investigation,
      or from under_investigation to any resolved state. This event
      enables downstream systems to track investigation lifecycle progress.
    subscribe:
      operationId: onIncidentStatusChanged
      summary: Incident investigation status changed
      description: >
        Fired when an analyst updates the investigation status of an incident
        or when automated workflows transition an incident to a resolved
        state. The payload reflects the new status at the time of the event.
      message:
        $ref: '#/components/messages/IncidentUpdated'
      bindings:
        http:
          method: POST

  incident/severity_changed:
    description: >
      Triggered when an incident's severity level is elevated or reduced,
      either automatically due to new correlated alerts or manually by
      an analyst overriding the calculated severity.
    subscribe:
      operationId: onIncidentSeverityChanged
      summary: Incident severity level changed
      description: >
        Fired when the severity of an incident changes, allowing downstream
        systems such as ticketing tools and escalation workflows to
        re-prioritize accordingly. The payload contains the updated severity
        value.
      message:
        $ref: '#/components/messages/IncidentUpdated'
      bindings:
        http:
          method: POST

  alert/created:
    description: >
      Triggered when a new alert is generated by Cortex XDR analytics
      engines, BIOC (Behavioral Indicator of Compromise) rules, IOC
      matches, endpoint agents, or third-party integrated data sources.
      Alerts represent individual suspicious or malicious activities
      detected across the protected environment.
    subscribe:
      operationId: onAlertCreated
      summary: New alert generated
      description: >
        Fired when Cortex XDR creates a new individual alert. The payload
        contains the alert name, incident association, creation and
        modification times, status, severity, alert count, assigned user,
        description, and alert source information.
      message:
        $ref: '#/components/messages/AlertCreated'
      bindings:
        http:
          method: POST

components:
  messages:
    IncidentCreated:
      name: IncidentCreated
      title: Incident Created
      summary: A new Cortex XDR incident has been created
      contentType: application/json
      payload:
        $ref: '#/components/schemas/IncidentPayload'
      examples:
      - name: RansomwareIncidentCreated
        summary: New ransomware incident created from correlated endpoint alerts
        payload:
          name: Ransomware Activity Detected on WORKSTATION-042
          incident_id: '5001'
          creation_time: 1705312200000
          modification_time: 1705312200000
          status: new
          severity: high
          alert_count: 3
          assigned_user_mail: [email protected]
          description: Multiple alerts indicating ransomware behavior on endpoint
          alert_sources:
          - XDR Agent
          - XDR Analytics BIOC

        x-microcks-default: true
    IncidentUpdated:
      name: IncidentUpdated
      title: Incident Updated
      summary: A Cortex XDR incident status or severity has changed
      contentType: application/json
      payload:
        $ref: '#/components/schemas/IncidentPayload'
      examples:
      - name: IncidentUnderInvestigation
        summary: Analyst assigns and begins investigating an incident
        payload:
          name: Ransomware Activity Detected on WORKSTATION-042
          incident_id: '5001'
          creation_time: 1705312200000
          modification_time: 1705315800000
          status: under_investigation
          severity: high
          alert_count: 5
          assigned_user_mail: [email protected]
          description: Multiple alerts indicating ransomware behavior on endpoint
          alert_sources:
          - XDR Agent
          - XDR Analytics BIOC

        x-microcks-default: true
    AlertCreated:
      name: AlertCreated
      title: Alert Created
      summary: A new Cortex XDR alert has been generated
      contentType: application/json
      payload:
        $ref: '#/components/schemas/AlertPayload'
      examples:
      - name: MaliciousProcessAlert
        summary: New alert for a malicious process execution on an endpoint
        payload:
          name: Malicious Process Execution - Mimikatz
          incident_id: '5001'
          creation_time: 1705312200000
          modification_time: 1705312200000
          status: new
          severity: high
          alert_count: 1
          assigned_user_mail: [email protected]
          description: >-
            Mimikatz credential dumping tool execution detected on
            WORKSTATION-042 under user context DOMAIN\jsmith
          alert_sources:
          - XDR Agent

        x-microcks-default: true
  schemas:
    IncidentPayload:
      type: object
      description: >
        The payload delivered to the webhook endpoint for Cortex XDR incident
        lifecycle events including creation, status changes, and severity
        changes. Contains incident metadata, alert aggregation counts,
        assignment information, and data source attribution.
      required:
      - name
      - incident_id
      - creation_time
      - modification_time
      - status
      - severity
      - alert_count
      - alert_sources
      properties:
        name:
          type: string
          description: >
            Human-readable name of the incident, either auto-generated by
            Cortex XDR from the correlated alert details or manually assigned
            by an analyst during investigation.
          example: Ransomware Activity Detected on WORKSTATION-042
        incident_id:
          type: string
          description: >
            The unique numeric identifier for the incident, assigned by
            Cortex XDR upon creation. Used to reference the incident in all
            subsequent API operations and webhook events.
          example: '5001'
        creation_time:
          type: integer
          description: >
            Unix epoch timestamp in milliseconds indicating when the incident
            was first created by Cortex XDR's correlation engine.
          example: 1705312200000
        modification_time:
          type: integer
          description: >
            Unix epoch timestamp in milliseconds indicating the most recent
            modification to the incident, including status changes, severity
            updates, alert additions, and analyst assignments.
          example: 1705315800000
        status:
          type: string
          description: >
            The current investigation status of the incident at the time this
            webhook notification was dispatched.
          enum:
          - new
          - under_investigation
          - resolved_threat_handled
          - resolved_known_issue
          - resolved_duplicate
          - resolved_false_positive
          - resolved_auto
          example: new
        severity:
          type: string
          description: >
            The current severity level of the incident, determined by the
            highest-severity correlated alert or manually overridden by an
            analyst. Drives prioritization in incident queues and escalation
            workflows.
          enum:
          - low
          - medium
          - high
          - critical
          example: high
        alert_count:
          type: integer
          description: >
            The total number of individual alerts that have been correlated
            and grouped into this incident at the time of this notification.
          minimum: 1
          example: 3
        assigned_user_mail:
          type: string
          description: >
            The email address of the analyst currently assigned to investigate
            this incident. Empty string when the incident is unassigned.
          format: email
          example: [email protected]
        description:
          type: string
          description: >
            A detailed description of the incident providing context about the
            detected threat activity, affected assets, and attack scope. May
            be auto-generated from correlated alert content or manually
            authored by an analyst.
          example: Multiple alerts indicating ransomware behavior on endpoint
        alert_sources:
          type: array
          description: >
            List of detection source identifiers that contributed alerts to
            this incident. Identifies which Cortex XDR engines, modules, or
            integrated third-party products generated the underlying alerts.
          items:
            type: string
            description: >
              Name of a detection source that contributed at least one alert
              to this incident.
          example:
          - XDR Agent
          - XDR Analytics BIOC

    AlertPayload:
      type: object
      description: >
        The payload delivered to the webhook endpoint for Cortex XDR alert
        creation events. Contains alert identification, incident association,
        timing metadata, status, severity, alert aggregation counts, assignee
        information, description, and contributing data sources.
      required:
      - name
      - incident_id
      - creation_time
      - modification_time
      - status
      - severity
      - alert_count
      - alert_sources
      properties:
        name:
          type: string
          description: >
            Human-readable name of the alert derived from the detection rule,
            analytics model, IOC match, or BIOC rule that triggered it.
          example: Malicious Process Execution - Mimikatz
        incident_id:
          type: string
          description: >
            The unique identifier of the parent incident to which this alert
            has been correlated. Enables association of individual alerts with
            their incident context.
          example: '5001'
        creation_time:
          type: integer
          description: >
            Unix epoch timestamp in milliseconds indicating when the alert
            was first generated by the detecting engine or agent.
          example: 1705312200000
        modification_time:
          type: integer
          description: >
            Unix epoch timestamp in milliseconds indicating the most recent
            modification to the alert record.
          example: 1705312200000
        status:
          type: string
          description: >
            The current status of the alert at the time this webhook
            notification was dispatched.
          enum:
          - new
          - under_investigation
          - resolved_threat_handled
          - resolved_known_issue
          - resolved_duplicate
          - resolved_false_positive
          - resolved_auto
          example: new
        severity:
          type: string
          description: >
            The severity level of the individual alert as determined by the
            detection rule, analytics model, or IOC threat intelligence that
            triggered it.
          enum:
          - low
          - medium
          - high
          - critical
          example: high
        alert_count:
          type: integer
          description: >
            The number of raw detection events aggregated into this alert.
            Multiple occurrences of the same detection within a time window
            may be consolidated into a single alert record.
          minimum: 1
          example: 1
        assigned_user_mail:
          type: string
          description: >
            The email address of the analyst assigned to investigate the
            parent incident of this alert. Empty string when unassigned.
          format: email
          example: ''
        description:
          type: string
          description: >
            A detailed description of the alert providing context about the
            detected malicious or suspicious activity, including process
            details, file paths, network connections, or user context.
          example: >-
            Mimikatz credential dumping tool execution detected on
            WORKSTATION-042 under user context DOMAIN\jsmith
        alert_sources:
          type: array
          description: >
            List of detection source identifiers that contributed to this
            alert. Identifies which Cortex XDR engine or module produced
            the detection.
          items:
            type: string
            description: >
              Name of the detection source (e.g., XDR Agent, XDR Analytics,
              XDR Analytics BIOC, XDR BIOC, Cortex XDR - IOC).
          example:
          - XDR Agent

  securitySchemes:
    hmacSignature:
      type: httpApiKey
      description: >
        An HMAC-SHA256 signature included in the X-XDR-HMAC-SHA256 HTTP
        header of each webhook request. Computed using the webhook secret
        configured in Cortex XDR notification settings. Recipients should
        validate this header to verify that payloads originate from Cortex
        XDR and have not been tampered with in transit.
      name: X-XDR-HMAC-SHA256
      in: header