action.skip

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:

Destinations cannot initiate actions. Only rules can initiate actions. A destination may be used in any number of rules.

Resource list

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

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