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

Create one destination.

Note

When you create a destination for PagerDuty, ServiceNow, or Slack, the credentials are not stored in the credentials 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 template

An abstract preview of a JSON request to create one destination.

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

Request fields

name (string, required)

A unique, short identifier for the destination.

Once created, the value of a name field cannot be changed.

description (string, optional)

Additional text to further describe the destination.

tags (array, optional)

A list of arbitrary terms to associate with the destination.

type (object, required)

An object that contains one destination type object.

Email

email (object, optional)

A destination type object that contains email destination properties.

to (string, required)

One email address.

subject (string, optional)

Text for the subject line of the email message.

body (string, optional)

Text for the body of the email message. Templates are supported.

Zenoss event service

event (object, optional)

A destination type object that contains Zenoss event service destination properties.

nameTemplate (string, required)

A name for the event. Templates are supported.

typeTemplate (string, required)

A context-free label to classify the event.

summaryTemplate (string, required)

A brief description of the event. Templates are supported.

severity (string, required)

The event severity.

• 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

bodyTemplate (string, optional)

A longer description of the event. Templates are supported.

Microsoft Teams

msteams (object, optional)

A destination type object that contains Microsoft Teams destination properties.

webhookUrl (string, required)

The URL of a Microsoft Teams incoming webhook for a target channel.

text (string, required)

The text to send to the channel associated with the specified webhook URL. Templates are supported.

facts (array, optional)

A list of up to 20 custom key-value pairs to use in place of the default connector card in notifications sent to a destination.

name (string, optional)

The key of a custom key-value pair.

value (string, optional)

The value of a custom key-value pair. Templates are supported.

PagerDuty

pagerduty (object, optional)

A destination type object that contains PagerDuty destination properties.

integrationKey (string, required)

A PagerDuty Integration Key.

The key is used to send an Alert Event to PagerDuty.

ServiceNow IT Operations Management

servicenow (object, optional)

A destination type object that contains ServiceNow destination properties.

baseUrl (string, required)

The URL of your ServiceNow IT Operations Management instance.

shortDescription (string, optional)

Text to include in all notifications sent to this destination. Templates are supported.

ServiceNow Basic authorization

basic (object, required)

An object that contains username-password authorization properties.

username (string, required)

The name of a user account in your ServiceNow IT Operations Management instance.

password (string, required)

The password of a user account in your ServiceNow IT Operations Management instance.

ServiceNow OAuth authorization

oauth (object, required)

An object that contains OAuth authorization properties.

username (string, optional)

A ServiceNow account to authorize a refresh token request.

password (string, optional)

The password of a ServiceNow account to authorize a refresh token request.

clientId (string, required)

The ServiceNow ID for your integration with Zenoss Cloud.

clientSecret (string, required)

The ServiceNow secret for your integration with Zenoss Cloud.

tokenUrl (string, required)

The URL for updating a ServiceNow refresh token.

authUrl (string, required)

The URL for obtaining a ServiceNow refresh token.

refreshToken (string, required)

A ServiceNow refresh token.

Slack

slack (object, optional)

A destination type object that contains Slack destination properties.

channel (string, required)

The name of a public channel in your Slack workspace.

Channel names that start with the number sign character are not accepted.

token (string, required)

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 (string, optional)

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.

Webhook

webhook (object, optional)

A destination type object that contains Webhook destination properties.

url (string, required)

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",
      "facts": [
        {
          "name": "Type",
          "value": "{{{event.type}}}"
        },
        {
          "name": "Severity",
          "value": "{{{event.severity}}}"
        }
      ]
    }
  },
  "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",
        "facts": [
          {
            "name": "Type",
            "value": "{{{event.type}}}"
          },
          {
            "name": "Severity",
            "value": "{{{event.severity}}}"
          }
        ]
      }
    }
  }
}

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}

Get one destination.

Response fields

Responses may include the following fields.

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 credential service entry associated with the destination.

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]

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

Query fields

The following query fields are supported. Each field may be used only once in a query. Searches determine whether the destination contains the specified value.

• name
• description
• type
• ruleNames
• tags

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

Response fields

Responses may include the following fields.

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 credential service entry associated with the destination.

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}

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

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

Delete 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

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

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