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: 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 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: unassigned@example.com 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: analyst@example.com 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: unassigned@example.com 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: analyst@example.com 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