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 `name` field cannot be changed.
`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. The key is the type to create (`email`, `event`, `msteams`, `pagerduty`, `servicenow`, `slack`, or `webhook`). The value is an object that further specifies the destination type to create.

Email

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: `SEVERITY_CRITICAL` Entity is down. `SEVERITY_ERROR` Entity is degraded but not down. `SEVERITY_WARNING` Action may be required in the future. `SEVERITY_INFO` Most likely, no action is required. `SEVERITY_DEBUG` By default, not severe enough to display in an events console.
`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 `basic` authorization type.
`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 `oauth` authorization type.
`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

Email

RequestResponse

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

RequestResponse

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

RequestResponse

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

RequestResponse

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

RequestResponse

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

RequestResponse

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

RequestResponse

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

RequestResponse

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

RequestResponse

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

RequestResponse

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

RequestResponse

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

RequestResponse

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

RequestResponse

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

RequestResponse

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"
      }
    }
  }
}