Working with the Event Monitoring & Notification API

This article explains how you can discover available event sources and create subscriptions to receive notifications when specific events occur in your Zscaler environment. The Event Monitoring & Notification API supports automated delivery of notifications using multiple channels, including email, webhook, and Amazon Simple Notification Service (SNS).

Prerequisites

Organizations must meet the following prerequisites before they can create and manage subscriptions:

Ensure that you have the Event Monitoring & Notification API service enabled for your tenant. To obtain access to this API service, contact your Zscaler Account team.
Register the API client application in Authentication Service and assign the Event Monitoring Subscribe role. This role provides view-only access to the service catalog and full access to subscriptions (i.e., create, update, and delete) within the Event Monitoring & Notification API.
Assign a role from the API product resource for which the notifications are subscribed. Currently, you can subscribe to notifications for ZPA, so a role from the ZPA product resource must be assigned.

To learn more about the API client setup and different authentication methods, see Getting Started. To learn how to register a client in Authentication Service, see Adding an API Client and Viewing API Resources.

NOTE

After your API client is created and provisioned in Authentication Service, the next step is to authenticate using the client's generated credentials. Authentication verifies your client's identity and issues an access token that must be sent in every subsequent API request using the Authorization header (i.e., Authorization: Bearer <Token>). To learn more, see Getting Started.

Creating Subscriptions Using Email and Webhook

Complete the following steps to create subscriptions using email and webhook notification channels.

Step 1: Browse the Service Catalog

As a first step, you must discover the list of available sources, source types, and source events. The service catalog is hierarchical: Sources → Source Types → Source Events. Each level provides _links to navigate to child items.

Retrieve the available sources by sending the following request:

curl -X GET https://api.zsapi.net/event-monitoring/catalog/sources \
 -H "Authorization: Bearer <Token>" 

Example response:

{
  "sources": [
    {
      "key": "zpa",
      "name": "Zscaler Private Access",
      "description": "ZPA event source",
      "_links": {
        "self": "/catalog/sources/zpa",
        "source_types": "/catalog/sources/zpa/source-types"
      }
    }
  ]
}

Follow the source_types link to see which types of events are available for each source.

Retrieve the available source types using the following request:

curl -X GET https://api.zsapi.net/event-monitoring/catalog/sources/zpa/source-types \
 -H "Authorization: Bearer <Token>" 

Example response:

{
  "sourceTypes": [
    {
      "key": "app_connector",
      "name": "App Connector",
      "description": "ZPA App Connector",
      "_links": {
        "self": "/catalog/sources/zpa/source-types/app_connector",
        "source_events": "/catalog/sources/zpa/source-types/app_connector/source-events"
      }
    }
  ]
}

Retrieve the source events using the following request. Source events are the specific event types that you can subscribe to. They include attributes that describe the data fields available for filtering.

curl -X GET https://api.zsapi.net/event-monitoring/catalog/sources/zpa/source-types/app_connector/source-events \
  -H "Authorization: Bearer <Token>"

Example response:

{
  "source_events": [
    {
      "key": "status",
      "name": "Connector Status",
      "description": "Status change event for a connector"
    }
  ]
}

Step 2: Create a Subscription

In this step, you can select which events you want to subscribe to and configure notification channels using an API request. You can subscribe to multiple source types and events within a single subscription.

The request specifies the event details within the scope object:

source_key: The source to be monitored for events (e.g., zpa)
source_type_key: The specific source type within that source (e.g., app_connector)
source_event_key: The specific events for which you want to receive alerts (e.g., status)

In addition, all subscription API calls require the following headers to identify the product tenant that you want to monitor:

x-em-cloud: Cloud identifier for the product tenant (e.g., prod.zpath.net)
x-em-tenant: Product tenant identifier for ZIA, ZPA, etc. (e.g., 145254691217866752)

You can create a subscription and configure an email or webhook notification channel, as shown in the following examples:

Email subscription:

curl -X POST https://api.zsapi.net/event-monitoring/subscriptions \
	-H "Authorization: Bearer <Token>" \
	-H "Content-Type: application/json" \
	-H "x-em-cloud: prod.zpath.net" \
	-H "x-em-tenant: 145254691217866752" \
	-d '{
	"name": "ZPA Connector Status Down",
	"description": "Get notified when a ZPA connector goes down",
	"scope": {
		"source_key": "zpa",
		"source_type_key": "app_connector",
		"source_event_key": "status"
	},
	"channels": [
		{
		"type": "email",
		"email": {
			"to": ["admin@example.com"],
			"cc": ["team@example.com"],
			"bcc": []
		}
		}
	],
	"enabled": true
	}'

Webhook subscription:

curl -X POST https://api.zsapi.net/event-monitoring/subscriptions \
	-H "Authorization: Bearer <Token>" \
	-H "Content-Type: application/json" \
	-H "x-em-cloud: prod.zpath.net" \
	-H "x-em-tenant: 145254691217866752" \
	-d '{
	"name": "ZPA Connector Alerts - Webhook",
	"description": "Send connector alerts to our webhook",
	"scope": {
		"source_key": "zpa",
		"source_type_key": "app_connector",
		"source_event_key": "status"
	},
	"channels": [
		{
		"type": "webhook",
		"webhook_url": "https://hooks.example.com/em-alerts"
		}
	],
	"enabled": true
	}'

You can also combine multiple channels in a single subscription. For example:

{
  "channels": [
    {
      "type": "email",
      "email": { "to": ["admin@example.com"] }
    },
    {
      "type": "webhook",
      "webhook_url": "https://hooks.example.com/em-alerts"
    }
  ]
}

After creating a subscription successfully, you receive email or webhook notifications when matching events occur.

Note

You can monitor multiple Zscaler services by creating separate subscriptions with different headers (x-em-cloud and x-em-tenant) for each product tenant. You can also create the required number of subscriptions for different events and channels.

Channel Validation Rules

The notification channels specified in the subscription requests must meet the following predefined criteria:

Channel	Field	Validation
Email	`email.to/cc/bcc`	Must match: `^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$`
Webhook	`webhook_url`	Must match: `^https?://.+$`

Creating Subscriptions Using Amazon SNS

The following steps outline an end-to-end setup and workflow for creating subscriptions using Amazon SNS:

Verify that SNS is available as a channel: Send a GET request to /subscriptions/channels and confirm that the sns channel is supported for your tenant.
Retrieve SNS setup requirements: Send a GET request to /subscriptions/channels/sns to obtain the Amazon Resource Name (ARN) for the Zscaler Identity and Access Management (IAM) role, required permissions, and the SNS topic policy template.
Create an SNS topic in your AWS account: Create a topic using the Amazon Web Services (AWS) SNS console, AWS CLI, or AWS CloudFormation (Standard or First-In-First-Out (FIFO), as required).
Apply the SNS topic policy: Associate a topic policy that grants the Zscaler IAM role permission to publish to your topic (for example, using aws sns set-topic-attributes).
Verify that Zscaler can access the topic: Send a POST request to /subscriptions/channels/sns:verify to confirm that the Event Monitoring & Notification API can access and publish to your SNS topic.
Create the Event Monitoring subscription: Send a POST request to /subscriptions to create a subscription that uses the sns channel.

After completing these steps, you will start receiving events on your SNS topic. When alert conditions are met, the Event Monitoring & Notification API publishes events to your topic asynchronously. Your SNS subscriptions then deliver messages to downstream systems (e.g., Amazon SQS, Amazon Lambda, and HTTP/HTTPS endpoints) according to your configuration.

Step 1: Discover Available Channels

Use GET /subscriptions/channels to retrieve the list of all notification channel types supported for your tenant, shown as follows.

Example request:

GET /subscriptions/channels HTTP/1.1
Host: api.zsapi.net
Authorization: Bearer <access-token>

Example response (200 OK):

{
  "channels": [
    {
      "type": "email",
      "description": "Email notifications",
      "setup_required": false,
      "_links": { "self": "/subscriptions/channels/email" }
    },
    {
      "type": "webhook",
      "description": "Webhook notifications",
      "setup_required": false,
      "_links": { "self": "/subscriptions/channels/webhook" }
    },
    {
      "type": "sns",
      "description": "AWS SNS topic notifications",
      "setup_required": true,
      "_links": {
        "self": "/subscriptions/channels/sns",
        "verify": "/subscriptions/channels/sns:verify"
      }
    }
  ]
}

NOTE

The sns entry with "setup_required": true indicates that additional configuration is needed before you can use the SNS channel. Follow the self link (/subscriptions/channels/sns) to view the SNS-specific setup requirements.

Use GET /subscriptions/channels/sns to retrieve the Zscaler IAM role ARN, the minimum required permissions, and a ready‑to‑use SNS topic policy template that you can apply to your SNS topic.

Example request:

GET /subscriptions/channels/sns HTTP/1.1
Host: api.zsapi.net
Authorization: Bearer <access-token>

Example response (200 OK)

{
  "type": "sns",
  "description": "AWS SNS topic notifications",
  "setup_required": true,
  "zscaler_role_arn": "arn:aws:iam::590183682394:role/CNS-SNS-Publisher",
  "required_permissions": [
    "sns:Publish",
    "sns:GetTopicAttributes"
  ],
  "sns_topic_policy_template": {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "AllowZscalerEventMonitoringPublish",
        "Effect": "Allow",
        "Principal": {
          "AWS": "arn:aws:iam::590183682394:role/CNS-SNS-Publisher"
        },
        "Action": [
          "sns:Publish",
          "sns:GetTopicAttributes"
        ],
        "Resource": "<customer_topic_arn>"
      }
    ]
  },
  "_links": {
    "self": "/subscriptions/channels/sns",
    "verify": "/subscriptions/channels/sns:verify",
    "subscriptions": "/subscriptions"
  }
}

From the response:

Note the zscaler_role_arn value. This is the Zscaler IAM role that will publish to your SNS topic.
Use sns_topic_policy_template when configuring your SNS topic policy in the next step.
Replace <customer_topic_arn> with the ARN of your SNS topic.

Create an SNS topic in your AWS account for receiving notifications. Both Standard topics and FIFO topics (with a .fifo suffix) are supported.

To learn how to create SNS topics, refer to the Amazon documentation.

AWS CLI examples

# Standard topic
aws sns create-topic \
  --name zscaler-em-events \
  --region us-west-2

# FIFO topic (name must end with `.fifo`)
aws sns create-topic \
  --name zscaler-em-events.fifo \
  --attributes FifoTopic=true,ContentBasedDeduplication=true \
  --region us-west-2

After you create the topic, note the returned TopicArn that is required in the following steps.

ARN Format:

arn:aws:sns:<region>:<account-id>:<topic-name>

Example:

arn:aws:sns:us-west-2:123456789012:zscaler-em-events

Grant the Zscaler publishing role permission to publish to your SNS topic by attaching a topic policy.

Create a file named policy.json with a policy based on the template returned by GET /subscriptions/channels/sns, replacing the Resource value with your topic ARN:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowZscalerEventMonitoringPublish",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::590183682394:role/CNS-SNS-Publisher"
      },
      "Action": [
        "sns:Publish",
        "sns:GetTopicAttributes"
      ],
      "Resource": "arn:aws:sns:us-west-2:123456789012:zscaler-em-events"
    }
  ]
}

Step 5: Verify that Zscaler Can Publish

Use POST /subscriptions/channels/sns:verify to validate that Zscaler can successfully call sns:GetTopicAttributes on your SNS topic. This is a read-only check; no test message is published to the topic.

Example request:

POST /subscriptions/channels/sns:verify HTTP/1.1
Host: api.zsapi.net
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "topic_arn": "arn:aws:sns:us-west-2:123456789012:zscaler-em-events",
  "region": "us-west-2"
}

The following table describes the request payload fields:

Field	Type	Required	Description
`topic_arn`	string	Yes	Full SNS topic ARN. Must match `arn:aws:sns:<region>:<12-digit-account>:<topic-name>` (optional `.fifo` suffix).
`region`	string	No	AWS region of the topic. If omitted, region is inferred from the ARN.

Example response for successful request (200 OK):

{
  "verified": true,
  "topic_arn": "arn:aws:sns:us-west-2:123456789012:zscaler-em-events",
  "message_sent": "{\"message\": \"Event Monitoring Message Test\"}"
}

Example response for failed request (code 400 or 422):

{
  "verified": false,
  "topic_arn": "arn:aws:sns:us-west-2:123456789012:zscaler-em-events",
  "error": "<Error that happened while verification>"
}

See possible HTTP response codes and troubleshooting steps

The following table provides information on HTTPS status codes used in responses and troubleshooting steps for common issues.

HTTPS Response Code	Description	Troubleshooting
200 OK	The Zscaler service successfully validated publish access to the SNS topic. It is safe to proceed and create a subscription.	Verification succeeded. You can proceed to create the subscription that uses the SNS channel.
400 Bad Request	The request is malformed (e.g., `topic_arn` is missing or the ARN doesn't match the required regex format).	Fix the request payload. Common issues include a missing `topic_arn` in the body or a malformed ARN (missing `region`, incorrect 12-digit account ID, or invalid characters in topic name).
404 Not Found	The endpoint URL is incorrect (e.g., typo in path, missing `/subscriptions/channels` prefix, etc.). This code is not used to indicate a missing SNS topic in AWS.	The endpoint path is wrong. Confirm that you are calling `POST /subscriptions/channels/sns:verify`.
422 Unprocessable Entity	The request is syntactically valid, but verification failed at AWS. For example, the Zscaler role does not have permission to call `sns:GetTopicAttributes` on the topic, the topic doesn't exist, or AWS returned another verification error.	The ARN format is correct, but the Zscaler service cannot actually verify the topic at AWS. Common causes include: The topic policy is missing or incorrectly configured (the Zscaler role does not have `sns:Publish` or `sns:GetTopicAttributes`). The topic does not exist in AWS. The wrong region was specified. Key Management Service (KMS) key access is missing if the topic is encrypted with a customer‑managed key.
500 Internal Server Error	Internal error in the Event Monitoring & Notification API service (not caused by the request).	Indicates a Zscaler-side issue. Wait briefly and retry with backoff. If the error continues, contact Zscaler Support.

Step 6: Create the Subscription

After SNS verification succeeds, use POST /subscriptions to create an event subscription that forwards specific events (e.g., ZPA App Connector status changes) to your SNS topic.

Example request:

POST /subscriptions HTTP/1.1
Host: api.zsapi.net
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "name": "ZPA App Connector Status to SNS",
  "description": "Forward ZPA App Connector UP/DOWN events to my SNS topic",
  "scope": {
    "source_key": "zpa",
    "source_type_key": "app_connector",
    "source_event_key": "status"
  },
  "channels": [
    {
      "type": "sns",
      "topic_arn": "arn:aws:sns:us-west-2:123456789012:zscaler-em-events",
      "region": "us-west-2"
    }
  ],
  "enabled": true
}

NOTE

You can attach multiple channels (for example, email, webhook, and SNS) to a single subscription. Each qualifying event is delivered to all configured channels.

Notification Payload Format

When the Event Monitoring & Notification API delivers an event to your SNS topic, Amazon SNS wraps the Zscaler event in a standard SNS envelope. The Zscaler event JSON is delivered as a string in the Message field.

Example full SNS envelope:

{
  "Type": "Notification",
  "MessageId": "22b4a1e5-6a3e-4f0d-9c3e-9a1b7c8d9e0f",
  "TopicArn": "arn:aws:sns:us-west-2:123456789012:zscaler-em-events",
  "Message": "{\"tenantId\":\"72059370006904832\",\"cloudName\":\"zpabeta.net\",\"occurredAt\":\"2026-07-07T21:40:47.205Z\",\"eventType\":\"zpa.app_connector.status\",\"oldValue\":\"DOWN\",\"newValue\":\"UP\",\"event\":\"STATE_CHANGE\",\"attributes\":{\"appConnectorId\":\"72059370006911322\",\"appConnectorName\":\"Oneapi-pk-1779994993712\",\"appConnectorGroupId\":\"72059370006905434\",\"appConnectorGroupName\":\"TechUp App Connector Group\"}}",
  "Timestamp": "2026-07-07T21:40:47.500Z",
  "SignatureVersion": "1",
  "Signature": "...",
  "SigningCertURL": "..."
}

Zscaler event payload (after JSON.parse(Message)):

{
  "tenantId": "72059370006904832",
  "cloudName": "zpabeta.net",
  "occurredAt": "2026-07-07T21:40:47.205Z",
  "eventType": "zpa.app_connector.status",
  "oldValue": "DOWN",
  "newValue": "UP",
  "event": "STATE_CHANGE",
  "attributes": {
    "appConnectorId": "72059370006911322",
    "appConnectorName": "Oneapi-pk-1779994993712",
    "appConnectorGroupId": "72059370006905434",
    "appConnectorGroupName": "TechUp App Connector Group"
  }
}

Managing Subscriptions

The following example requests demonstrate how you can view a list of your subscriptions and update, disable, or delete a subscription.

Retrieve Subscriptions

The following example retrieves the list of your configured subscriptions with paginated results.

curl -X GET "https://api.zsapi.net/event-monitoring/subscriptions?page=0&pageSize=10" \
  -H "Authorization: Bearer <Token>" \
  -H "x-em-cloud: prod.zpath.net" \
  -H "x-em-tenant: 145254691217866752"

Update a Subscription

The following example request shows how to update an existing subscription.

curl -X PUT https://api.zsapi.net/event-monitoring/subscriptions/<subscription-id> \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/json" \
  -H "x-em-cloud: prod.zpath.net" \
  -H "x-em-tenant: 145254691217866752" \
  -d '{ ... updated subscription body ... }

Disable a Subscription

Set "enabled": false in the update request to temporarily disable a subscription without deleting it. When a subscription is disabled, notifications are no longer sent, but the subscription configuration is preserved.

Delete a Subscription

The following example request shows how you can delete a subscription.

curl -X DELETE https://api.zsapi.net/event-monitoring/subscriptions/<subscription-id> \
  -H "Authorization: Bearer <Token>" \
  -H "x-em-cloud: prod.zpath.net" \
  -H "x-em-tenant: 145254691217866752"

A successful delete request returns a 204 No Content response.

Security Best Practices

TLS required: All data in transit must be encrypted.
Tenant isolation: Isolation is enforced by authorization constraints and tenant mapping validation.
Audit logging: All operations log tenant ID, trace ID, API client ID, client IP address, and the change details (i.e., what was created, updated, or deleted).

Troubleshooting

The following sections provide troubleshooting tips for common issues encountered when operating, integrating with, or developing using the Event Monitoring & Notification API service to create and manage subscriptions.

Subscription Not Receiving Notifications

Try the following:

Check your subscription enablement status by sending a GET /subscriptions/{id} request with your subscription ID and verifying the "enabled": true setting in the response.
Check the scope to ensure that source_key, source_type_key, and source_event_key match the events being produced.
Check your subscription's product tenant ID (i.e., zpa_tenant_id) to verify what the subscription is for.

Email Not Delivered

Verify that the email address matches the expected format: ^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$

Webhook Not Receiving Calls

Try the following:

Verify that the URL matches the expected format: ^https?://.+$
Ensure that the webhook endpoint is reachable from the API deployment network.
Check for TLS certificate issues when using HTTPS.

Prerequisites

Creating Subscriptions Using Email and Webhook

Step 1: Browse the Service Catalog​

Step 2: Create a Subscription​

Channel Validation Rules​

Creating Subscriptions Using Amazon SNS

Step 1: Discover Available Channels​

Step 2: Retrieve SNS Setup Requirements​

Step 3: Create Your SNS Topic​

Step 4: Apply the SNS Topic Policy​

Step 5: Verify that Zscaler Can Publish​

Step 6: Create the Subscription​

Notification Payload Format​

Managing Subscriptions

Retrieve Subscriptions​

Update a Subscription​

Disable a Subscription​

Delete a Subscription​

Security Best Practices

Troubleshooting

Subscription Not Receiving Notifications​

Email Not Delivered​

Webhook Not Receiving Calls​

Step 1: Browse the Service Catalog

Step 2: Create a Subscription

Channel Validation Rules

Step 1: Discover Available Channels

Step 2: Retrieve SNS Setup Requirements

Step 3: Create Your SNS Topic

Step 4: Apply the SNS Topic Policy

Step 5: Verify that Zscaler Can Publish

Step 6: Create the Subscription

Notification Payload Format

Retrieve Subscriptions

Update a Subscription

Disable a Subscription

Delete a Subscription

Subscription Not Receiving Notifications

Email Not Delivered

Webhook Not Receiving Calls