Destination resources

A destination specifies the target of an action, the receiving application of a one-way message (a notification). Virtana Service Observability supports the following destinations:

Email addresses
Virtana Service Observability 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 all or 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

Create one destination.

Note

When you create a destination for PagerDuty, ServiceNow, or Slack, the credentials are not stored in the Credentials management service. To ensure all credentials are maintained in the credentials service, use the browser interface to create the destinations.

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.

Request fields

The following fields apply to all destination types.

Table 266. Common fields

Field	Type	Required	Description
`name`	string	Yes	A unique, short identifier for the destination. Once created, this value cannot be changed.
`description`	string	No	Additional text to further describe the destination.
`tags`	array	No	A list of arbitrary terms to associate with the destination.
`type`	object	Yes	An object that contains one destination type object.

Table 267. Email fields

Field	Type	Required	Description
`type.email`	object	No	A destination type object that contains email destination properties.
`type.email.to`	string	Yes	One email address.
`type.email.subject`	string	No	Text for the subject line of the email message.
`type.email.body`	string	No	Text for the body of the email message.

Table 268. Virtana Service Observability event service fields

Field	Type	Required	Description
`type.event`	object	No	A destination type object that contains Virtana event service destination properties.
`type.event.nameTemplate`	string	Yes	A name for the event.
`type.event.typeTemplate`	string	Yes	A context-free label to classify the event.
`type.event.summaryTemplate`	string	Yes	A brief description of the event.
`type.event.severity`	string	Yes	The event severity. Accepted values: `SEVERITY_DEBUG`: By default, not severe enough to display in an events console. `SEVERITY_INFO`: Most likely, no action is required. `SEVERITY_WARNING`: Action may be required in the future. `SEVERITY_ERROR`: Entity is degraded but not down. `SEVERITY_CRITICAL`: Entity is down.
`type.event.bodyTemplate`	string	No	A longer description of the event.

Table 269. Microsoft Teams fields

Field	Type	Required	Description
`type.msteams`	object	No	A destination type object that contains Microsoft Teams destination properties.
`type.msteams.webhookUrl`	string	Yes	The URL of a Microsoft Teams incoming webhook for a target channel.
`type.msteams.text`	string	Yes	The text to send to the channel associated with the specified webhook URL.
`type.msteams.facts`	array	No	A list of up to 20 custom key-value pairs to use in place of the default Office 365 connector card in notifications sent to a destination.
`type.msteams.facts.name`	string	No	The key of a custom key-value pair.
`type.msteams.facts.value`	string	No	The value of a custom key-value pair.

Table 270. PagerDuty fields

Field	Type	Required	Description
`type.pagerduty`	object	No	A destination type object that contains PagerDuty destination properties.
`type.pagerduty.integrationKey`	string	Yes	A PagerDuty Integration Key used to send an Alert Event to PagerDuty.

Table 271. ServiceNow IT Operations Management fields

Field	Type	Required	Description
`type.servicenow`	object	No	A destination type object that contains ServiceNow destination properties.
`type.servicenow.baseUrl`	string	Yes	The URL of your ServiceNow IT Operations Management instance.
`type.servicenow.shortDescription`	string	No	Text to include in all notifications sent to this destination.

Table 272. ServiceNow Basic authorization fields

Field	Type	Required	Description
`type.servicenow.basic`	object	Yes	An object that contains username-password authorization properties.
`type.servicenow.basic.username`	string	Yes	The name of a user account in your ServiceNow IT Operations Management instance.
`type.servicenow.basic.password`	string	Yes	The password of a user account in your ServiceNow IT Operations Management instance.

Table 273. ServiceNow OAuth authorization fields

Field	Type	Required	Description
`type.servicenow.oauth`	object	Yes	An object that contains OAuth authorization properties.
`type.servicenow.oauth.username`	string	No	A ServiceNow account to authorize a refresh token request.
`type.servicenow.oauth.password`	string	No	The password of a ServiceNow account to authorize a refresh token request.
`type.servicenow.oauth.clientId`	string	Yes	The ServiceNow ID for your integration with Virtana Service Observability.
`type.servicenow.oauth.clientSecret`	string	Yes	The ServiceNow secret for your integration with Virtana Service Observability.
`type.servicenow.oauth.tokenUrl`	string	Yes	The URL for updating a ServiceNow refresh token.
`type.servicenow.oauth.authUrl`	string	Yes	The URL for obtaining a ServiceNow refresh token.
`type.servicenow.oauth.refreshToken`	string	Yes	A ServiceNow refresh token.

Table 274. Slack fields

Field	Type	Required	Description
`type.slack`	object	No	A destination type object that contains Slack destination properties.
`type.slack.channel`	string	Yes	The name of a public channel in your Slack workspace. Channel names that start with the number sign character are not accepted.
`type.slack.token`	string	Yes	A bot token provided by the Virtana Slack app. To use a Slack channel in a destination, first install the Virtana Slack app in your workspace.
`type.slack.color`	string	No	The color to use in messages sent to a channel. The color is applied to a vertical bar accompanying the message block. Standard HTML color codes are supported.

Table 275. Webhook fields

Field	Type	Required	Description
`type.webhook`	object	No	A destination type object that contains webhook destination properties.
`type.webhook.url`	string	Yes	The URL of a webhook receiver. Virtana Service Observability uses POST to send to the receiver.

Request template

{
  "name": "<name>",
  "description": "<description>",
  "tags": [ "<tag>" ],
  "type": {
    "<type>": {
      "<key>": <value>,
      "<key>": <value>
    }
  }
}

GET /v1/notification/destinations/{name}

Get one destination.

Response fields

Responses may include the following fields.

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.

For PagerDuty, ServiceNow, and Slack destinations, additional fields identify the Credentials service entry associated with the destination.

Status codes

Code	Description
200	Success. The request was processed. Check the response body for per-item results when processing multiple objects.
404	Not found. The specified resource does not exist.

Example

Request example

curl https://YOUR-API-ENDPOINT/v1/notification/destinations/YOUR-DESTINATION-NAME \
  -H "zenoss-api-key: YOUR-API-KEY" -X GET -s

Response example

{
  "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]

Get all destinations or destinations that match a query. Requests with no queries will return all destinations.

Queries may be appended to the base URL with standard query syntax. See the query string example.

Query fields

Field	Description
`description`
`name`
`ruleNames`
`tags`
`type`

For more information about query fields, see the create a destination resource.

Response fields

Responses may include the following fields.

Field	Description
`recentNotificationCount`	The total number of notifications sent to this destination in the last 24 hours.
`totalCount`	The total number of destinations returned.

For PagerDuty, ServiceNow, and Slack destinations, additional fields identify the Credentials service entry associated with the destination.

Status codes

Code	Description
200	Success. The request was processed. Check the response body for per-item results when processing multiple objects.

All destinations example

Request example

curl https://YOUR-API-ENDPOINT/v1/notification/destinations \
  -H "zenoss-api-key: YOUR-API-KEY" -X GET -s

Response example

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

Request example

curl https://YOUR-API-ENDPOINT/v1/notification/destinations?type=slack \
  -H "zenoss-api-key: YOUR-API-KEY" -X GET -s

Response example

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

Update 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.

Request fields

Update requests use the same fields as create requests.

Status codes

Code	Description
200	Success. The request was processed. Check the response body for per-item results when processing multiple objects.
400	Bad request. The request body is missing, malformed, or contains invalid values.
404	Not found. The specified resource does not exist.

Example

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

Response example

{
  "destination": {
    "name": "YOUR-DESTINATION-NAME",
    "description": "Webhook URL",
    "type": {
      "webhook": {
        "url": "https://webhook.example.com/etc/updated"
      }
    }
  }
}

DELETE/v1/notification/destinations/{name}

Delete a destination.

Use the get multiple destinations resource to get destination names.

Status codes

Code	Description
200	Success. The request was processed. Check the response body for per-item results when processing multiple objects.
404	Not found. The specified resource does not exist.
412	Precondition failed. The destination is used in at least one rule.

Example

Request example

curl https://YOUR-API-ENDPOINT/v1/notification/destinations/YOUR-DESTINATION-NAME \
  -H "zenoss-api-key: YOUR-API-KEY" -X DELETE -s

Response example

{}

POST /v1/notification/destinations:test

Send a test notification to a destination.

The destination you specify is not saved and does not have to be an existing destination.

Status codes

Code	Description
200	Success. The request was processed. Check the response body for per-item results when processing multiple objects.
400	Bad request. The request body is missing, malformed, or contains invalid values.

Example

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

Response example

{
  "destination": {
    "name": "destination-test",
    "description": "Send test to example webhook URL",
    "type": {
      "webhook": {
        "url": "https://webhook.example.com/test"
      }
    }
  }
}

In this section:

Destination resources

Resource list

POST /v1/notification/destinations

Note

Note

Request fields

Request template

GET /v1/notification/destinations/{name}

Response fields

Status codes

Example

GET /v1/notification/destinations[?query]

Query fields

Response fields

Status codes

All destinations example

Query string example

PUT /v1/notification/destinations/{name}

Note

Request fields

Status codes

Example

DELETE/v1/notification/destinations/{name}

Status codes

Example

POST /v1/notification/destinations:test

Status codes

Example

Search results