Destination resources
A destination specifies the target of an action, the receiving application of a one-way message (a notification). Zenoss Cloud supports the following destinations:
- Email addresses
- Zenoss event service
- Microsoft Teams channels
- PagerDuty Alert Events
- ServiceNow IT Operations Management
- Public channels in Slack workspaces
- Any application that supports webhooks
Destinations cannot initiate actions. Only rules can initiate actions. A destination may be used in any number of rules.
Resource list
- Create a destination (POST /v1/notification/destinations)
- Get one destination (GET /v1/notification/destinations/{name})
- Get multiple destinations (GET /v1/notification/destinations[?query])
- Update a destination (PUT /v1/notification/destinations/{name})
- Delete a destination (DELETE/v1/notification/destinations/{name})
- Test a destination (POST /v1/notification/destinations:test)
POST /v1/notification/destinations
Creates one destination.
You can test a destination before creating it with the test a destination resource.
Note
Slack and webhook destinations receive the customized message defined in
a rule, while email destinations receive the message defined with the
subject
and body
fields of the destination.
Fields
All destinations
Field | Required? | Type | Description |
---|---|---|---|
name |
Yes | String | A unique, short identifier for the destination. Once created, a destination's |
description |
No | String | Additional text to further describe the destination. |
tags |
No | String | A list of arbitrary terms to associate with the destination. |
type |
Yes | Object | One key-value pair specifying the type of destination.
|
Field | Required? | Type | Description |
---|---|---|---|
to |
Yes | String | One email address. |
subject |
No | String | Text for the subject line of the email message. |
body |
No | String | Text for the body of the email message. Templates are supported. |
Zenoss event service
Field | Required? | Type | Description |
---|---|---|---|
nameTemplate |
Yes | String | A name for the event (templates supported). |
typeTemplate |
Yes | String | A context-free label to classify the event. |
summaryTemplate |
Yes | String | A brief description of the event (templates supported). |
severity |
Yes | String | The event severity, one of the following:
|
bodyTemplate |
No | String | A longer description of the event (templates supported). |
Microsoft Teams
Field | Required? | Type | Description |
---|---|---|---|
webhookUrl |
Yes | String | The URL of a Microsoft Teams incoming webhook for a target channel. |
text |
Yes | String | The text to send to the channel associated with the specified webhook URL. Templates are supported. |
PagerDuty
Field | Required? | Type | Description |
---|---|---|---|
integrationKey |
Yes | String | A PagerDuty Integration Key. The key is used to send an Alert Event to PagerDuty. |
ServiceNow IT Operations Management
Basic authorization
Field | Required? | Type | Description |
---|---|---|---|
baseUrl |
Yes | String | The URL of your ServiceNow IT Operations Management instance. |
shortDescription |
No | String | Text to include in all notifications sent to this destination. Templates are supported. |
basic |
Yes | Object | The authorization to use. The remaining fields of this table specify the |
username |
Yes | String | The name of a user account in your ServiceNow IT Operations Management instance. |
password |
Yes | String | The password of a user account in your ServiceNow IT Operations Management instance. |
OAuth authorization
Field | Required? | Type | Description |
---|---|---|---|
baseUrl |
Yes | String | The URL of your ServiceNow IT Operations Management instance. | oauth |
Yes | Object | The authorization to use. The remaining fields of this table specify the |
username |
No | String | A ServiceNow account to authorize a refresh token request. |
password |
No | String | The password of a ServiceNow account to authorize a refresh token request. |
clientId |
Yes | String | The ServiceNow ID for your integration with Zenoss Cloud. |
clientSecret |
Yes | String | The ServiceNow secret for your integration with Zenoss Cloud. |
tokenUrl |
Yes | String | The URL for updating a ServiceNow refresh token. |
authUrl |
Yes | String | The URL for obtaining a ServiceNow refresh token. |
refreshToken |
Yes | String | A ServiceNow refresh token. |
Slack
Field | Required? | Type | Description |
---|---|---|---|
channel |
Yes | String | The name of a public channel in your Slack workspace. Channel names that start with the number sign character are not accepted. |
token |
Yes | String | A bot token provided by the Zenoss Slack app. To use a Slack channel in a destination, first install the Zenoss Slack app in your workspace. |
color |
No | String | The color to use in messages sent to the channel. The color is applied to a vertical bar accompanying the message block. Standard HTML color codes are supported. |
Webhook
Field | Required? | Type | Description |
---|---|---|---|
url |
Yes | String | The URL of a webhook receiver. Zenoss Cloud uses POST to send a JSON message to the receiver. |
Status codes
- 200 (OK: destination was created)
- 400 (Bad Request: invalid destination)
- 409 (Conflict: a destination with the same name already exists)
Examples
curl https://YOUR-API-ENDPOINT/v1/notification/destinations \
-H "content-type: application/json" \
-H "zenoss-api-key: YOUR-API-KEY" \
-X POST -s -S -d \
'{
"name": "test-dest",
"description": "Test email destination",
"type": {
"email": {
"to": "test@example.com"
}
}
}'
{
"destination": {
"name": "test-dest",
"description": "Test email destination",
"type": {
"email": {
"to": "test@example.com"
}
}
}
}
Zenoss event service
curl https://YOUR-API-ENDPOINT/v1/notification/destinations \
-H "content-type: application/json" \
-H "zenoss-api-key: YOUR-API-KEY" \
-X POST -s -S -d \
'{
"name": "marketing-event-3",
"description": "Marketing system event",
"tags": [
"Marketing"
],
"type": {
"event": {
"summaryTemplate": "{{{destination.description}}}",
"severity": "SEVERITY_CRITICAL",
"nameTemplate": "{{{destination.name}}}",
"typeTemplate": "actions.event.marketing"
}
}
}'
{
"destination": {
"name": "marketing-event-3",
"description": "Marketing system event",
"type": {
"event": {
"summaryTemplate": "{{{destination.description}}}",
"severity": "SEVERITY_CRITICAL",
"nameTemplate": "{{{destination.name}}}",
"typeTemplate": "actions.event.marketing"
}
},
"tags": [
"Marketing"
]
}
}
Microsoft Teams
curl https://YOUR-API-ENDPOINT/v1/notification/destinations \
-H "content-type: application/json" \
-H "zenoss-api-key: YOUR-API-KEY" \
-X POST -s -S -d \
'{
"name": "test-msteams",
"type": {
"msteams": {
"url": "https://YOUR-SUBDOMAIN.webhook.office.com/YOUR-RESOURCE",
"text": "A message"
}
},
"description": "Test Microsoft Teams destination"
}'
{
"destination": {
"name": "test-msteams",
"description": "Test Microsoft Teams destination",
"type": {
"msteams": {
"webhookUrl": "https://YOUR-SUBDOMAIN.webhook.office.com/YOUR-RESOURCE",
"text": "A message"
}
}
}
}
PagerDuty
curl https://YOUR-API-ENDPOINT/v1/notification/destinations \
-H "content-type: application/json" \
-H "zenoss-api-key: YOUR-API-KEY" \
-X POST -s -S -d \
'{
"name": "test-pagerduty",
"type": {
"pagerduty": {
"integrationKey": "YOUR-ROUTING-KEY"
}
},
"description": "Test PagerDuty destination"
}'
{
"destination": {
"name": "test-pagerduty",
"description": "Test PagerDuty destination",
"type": {
"pagerduty": {
"integrationKey": "YOUR-ROUTING-KEY"
}
}
}
}
ServiceNow/Basic
curl https://YOUR-API-ENDPOINT/v1/notification/destinations \
-H "content-type: application/json" \
-H "zenoss-api-key: YOUR-API-KEY" \
-X POST -s -S -d \
'{
"name": "test-servicenow-basic",
"type": {
"servicenow": {
"baseUrl": "https://YOUR-TENANT.service-now.com/",
"basic": {
"username": "YOUR-ACCOUNT",
"password": "YOUR-PASSWORD"
},
"shortDescription": "Basic test"
}
}
}'
{
"destination": {
"name": "test-servicenow-basic",
"type": {
"servicenow": {
"basic": {
"username": "YOUR-ACCOUNT",
"password": "YOUR-PASSWORD"
},
"baseUrl": "https://YOUR-TENANT.service-now.com/",
"shortDescription": "Basic test"
}
}
}
}
ServiceNow/OAuth
curl https://YOUR-API-ENDPOINT/v1/notification/destinations \
-H "content-type: application/json" \
-H "zenoss-api-key: YOUR-API-KEY" \
-X POST -s -S -d \
'{
"name": "test-servicenow-oauth",
"type": {
"servicenow": {
"baseUrl": "https://YOUR-TENANT.service-now.com/",
"oauth": {
"clientId": "YOUR-CLIENT-ID",
"clientSecret": "YOUR-CLIENT-SECRET",
"refreshToken": "YOUR-TOKEN",
"authUrl": "https://YOUR-TENANT.service-now.com/oauth_auth.do",
"tokenUrl": "https://YOUR-TENANT.service-now.com/oauth_token.do"
}
}
}
}'
{
"destination": {
"name": "test-servicenow-oauth",
"type": {
"servicenow": {
"oauth": {
"clientId": "YOUR-CLIENT-ID",
"clientSecret": "YOUR-CLIENT-SECRET",
"refreshToken": "YOUR-TOKEN",
"authUrl": "https://YOUR-TENANT.service-now.com/oauth_auth.do",
"tokenUrl": "https://YOUR-TENANT.service-now.com/oauth_token.do"
},
"baseUrl": "https://YOUR-TENANT.service-now.com/"
}
}
}
}
Slack
curl https://YOUR-API-ENDPOINT/v1/notification/destinations \
-H "content-type: application/json" \
-H "zenoss-api-key: YOUR-API-KEY" \
-X POST -s -S -d \
'{
"name": "test-slack",
"description": "Test Slack destination",
"type": {
"slack": {
"channel": "zenoss-cloud",
"token": "YOUR-BOT-TOKEN"
}
}
}'
{
"destination": {
"name": "test-slack",
"description": "Test Slack destination",
"type": {
"slack": {
"channel": "zenoss-cloud",
"token": "YOUR-BOT-TOKEN"
}
}
}
}
Webhook
curl https://YOUR-API-ENDPOINT/v1/notification/destinations \
-H "content-type: application/json" \
-H "zenoss-api-key: YOUR-API-KEY" \
-X POST -s -S -d \
'{
"name": "test-webhook",
"description": "Test webhook destination",
"type": {
"webhook": {
"url": "https://webhook.example.com/test"
}
}
}'
{
"destination": {
"name": "test-webhook",
"description": "Test webhook destination",
"type": {
"webhook": {
"url": "https://webhook.example.com/test"
}
}
}
}
GET /v1/notification/destinations/{name}
Gets one destination.
Fields
Responses may include fields from the following table.
Field | Description |
---|---|
ruleNames |
The list of rules that use the destination. |
recentNotificationCount |
The total number of notifications sent to this destination in the last 24 hours. |
Status codes
- 200 (OK: destination exists)
- 404 (Not Found: destination does not exist)
Example
curl https://YOUR-API-ENDPOINT/v1/notification/destinations/YOUR-DESTINATION-NAME \
-H "zenoss-api-key: YOUR-API-KEY" -X GET -s
{
"destination": {
"name": "YOUR-DESTINATION-NAME",
"description": "Slack destination.",
"type": {
"slack": {
"token": "YOUR-BOT-TOKEN",
"channel": "notification_sender",
"color": "#FFFFFF"
}
},
"tags": [
"test",
"slack"
]
}
}
GET /v1/notification/destinations[?query]
Gets all destinations or destinations that match a query.
Queries may be appended to the base URL with standard query syntax. See the query string example.
Fields
Query fields
Field | Value | Comparison | Repeat? |
---|---|---|---|
name |
String | Contains | No (may be used only once) |
description |
String | Contains | No |
type |
String | Contains | No |
ruleNames |
String | Contains | No |
tags |
String | Contains | No |
For more information about query fields, see the create a destination resource.
Response fields
Field | Description |
---|---|
recentNotificationCount |
The total number of notifications sent to a destination in the last 24 hours, if any. |
totalCount |
The total number of destinations returned. |
Status codes
- 200 (OK)
All destinations example
curl https://YOUR-API-ENDPOINT/v1/notification/destinations \
-H "zenoss-api-key: YOUR-API-KEY" -X GET -s
{
"destinations": [
{
"name": "Slack-Test",
"description": "Slack Test",
"type": {
"slack": {
"token": "YOUR-BOT-TOKEN",
"channel": "YOUR-SLACK-CHANNEL"
}
},
"ruleNames": [
"Test-Rule1",
"Test-Rule3"
]
},
{
"name": "Webhook.Site",
"type": {
"webhook": {
"url": "YOUR-WEBHOOK-URL"
}
},
"ruleNames": [
"TestingWebHook.Site"
],
"tags": [
"WebhookTag"
]
},
{
"name": "test-dest",
"description": "Test Destination",
"type": {
"email": {
"to": "test@example.com, test2@example.com",
"body": "Test destination body",
"subject": "Test destination subject"
}
}
}
],
"totalCount": "3"
}
Query string example
curl https://YOUR-API-ENDPOINT/v1/notification/destinations?type=slack \
-H "zenoss-api-key: YOUR-API-KEY" -X GET -s
{
"destinations": [
{
"name": "Example1",
"description": "Example",
"type": {
"slack": {
"token": "YOUR-BOT-TOKEN",
"channel": "test_notifications"
}
},
"ruleNames": [
"My new Rule"
],
"tags": [
"Example "
]
},
{
"name": "eXAMPLE2",
"type": {
"slack": {
"token": "YOUR-BOT-TOKEN",
"channel": "okmet_test",
"color": "#000000"
}
},
"ruleNames": [
"event2_rule",
"event_rule "
],
"recentNotificationCount": "1"
}
],
"totalCount": "2"
}
PUT /v1/notification/destinations/{name}
Updates an existing destination.
Unspecified fields are deleted. Destination names cannot be changed.
Note
Slack and webhook destinations receive the customized message defined in
a rule, while email destinations receive the message defined with the
subject
and body
fields of the destination.
Fields
See the fields in the create destination resource.
Status codes
- 200 (OK: destination was updated)
- 400 (Bad Request: invalid destination)
- 404 (Not Found: destination doesn't exist)
Example
curl https://YOUR-API-ENDPOINT/v1/notification/destinations/YOUR-DESTINATION-NAME \
-H "zenoss-api-key: YOUR-API-KEY" \
-X PUT -s -S -d \
'{
"type": {
"webhook": {
"url": "https://webhook.example.com/etc/updated"
}
}
}'
{
"destination": {
"name": "YOUR-DESTINATION-NAME",
"description": "Webhook URL",
"type": {
"webhook": {
"url": "https://webhook.example.com/etc/updated"
}
}
}
}
DELETE/v1/notification/destinations/{name}
Deletes a destination.
Use the get multiple destinations resource to get destination names.
Status codes
- 200 (OK: destination was deleted)
- 404 (Not Found: destination doesn't exist)
- 412 (Precondition Failed: destination is used in at least one rule)
Example
curl https://YOUR-API-ENDPOINT/v1/notification/destinations/YOUR-DESTINATION-NAME \
-H "zenoss-api-key: YOUR-API-KEY" -X DELETE -s
{}
POST /v1/notification/destinations:test
Sends a test notification to a destination.
The destination you specify is not saved and does not have to be an existing destination.
Status codes
- 200 (OK: test notification was sent to destination)
- 400 (Bad Request: invalid destination)
Example
curl https://YOUR-API-ENDPOINT/v1/notification/destinations:test \
-H "zenoss-api-key: YOUR-API-KEY" \
-X POST -s -S -d \
'{
"name": "destination-test",
"description": "Send test to example webhook URL",
"type": {
"webhook": {
"url": "https://webhook.example.com/test"
}
}
}'
{
"destination": {
"name": "destination-test",
"description": "Send test to example webhook URL",
"type": {
"webhook": {
"url": "https://webhook.example.com/test"
}
}
}
}