Skip to content

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:

  • Public channels in Slack workspaces
  • Any application that supports webhooks
  • Email addresses

Destinations cannot initiate actions. Only rules can initiate actions.

A destination may be used in any number of rules. To use a Slack channel in a destination, first install the "Zenoss" Slack app in your workspace.

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.

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

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, slack, or webhook).
  • The value is an object that further specifies the destination type to create.

Field Required? Type Description
to Yes String One email address.
subject No String Text for the subject line of the email message. You can include one or more templates in the text.
body No String Text for the body of the email message. You can include one or more templates in the text.

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.

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)

Email example

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, test2@example.com",
      "subject": "Test destination subject",
      "body": "Test destination body"
    }
  }
}'
{
  "destination": {
    "name": "test-dest",
    "description": "Test email destination",
    "type": {
      "email": {
        "to": "test@example.com, test2@example.com",
        "body": "Test destination body",
        "subject": "Test destination subject"
      }
    }
  }
}

Slack example

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 example

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

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, slack, or webhook).
  • The value is an object that further specifies the destination type to create.

Field Required? Type Description
to Yes String One email address.
subject No String Text for the subject line of the email message. You can include one or more templates in the text.
body No String Text for the body of the email message. You can include one or more templates in the text.

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.

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

Example JSON message for webhook destination

Zenoss Cloud sends JSON messages to webhook destinations.

{
  "id": "AAAABg6X6wV4Sv-3-zQ7kcxJaqg=",
  "tenant": "YOUR-TENANT-NAME",
  "timestamp": 1628612762112,
  "rule": {
    "name": "test-rule-2",
    "trigger_names": [
      "test-trigger-event-1"
    ],
    "destination_names": [
      "test-webhook-1"
    ],
    "message": "Message content",
    "enabled": true,
    "repeat_interval": 3600
  },
  "trigger": {
    "name": "test-trigger-event-1",
    "type": {
      "TriggerType": {
        "Event": {
          "query": {
            "clause": {
              "Clause": {
                "And": {
                  "clauses": [
                    {
                      "Clause": {
                        "Equals": {
                          "field": "severity",
                          "value": {
                            "Value": {
                              "StringVal": "critical"
                            }
                          }
                        }
                      }
                    },
                    {
                      "Clause": {
                        "Equals": {
                          "field": "status",
                          "value": {
                            "Value": {
                              "StringVal": "open"
                            }
                          }
                        }
                      }
                    },
                    {
                      "Clause": {
                        "Equals": {
                          "field": "source",
                          "value": {
                            "Value": {
                              "StringVal": "my.simple.app.one"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "destination": {
    "name": "test-webhook-1",
    "type": {
      "DestinationType": {
        "Webhook": {
          "url": "YOUR-WEBHOOK-URL"
        }
      }
    }
  },
  "context": {
    "Context": {
      "Event": {
        "id": "AAAABfIrtGYvfx6V1S-AyN7buRc=",
        "tenant": "YOUR-TENANT-NAME",
        "timestamp": 1628612716000,
        "name": "test-event-3",
        "dimensions": {
          "source": {
            "Value": {
              "StringVal": "my.simple.app.one"
            }
          },
          "source-type": {
            "Value": {
              "StringVal": "com.example.simple"
            }
          }
        },
        "metadata": {
          "_zen_applied_policy": {
            "scalars": [
              {
                "Value": {
                  "StringVal": "default:INGEST:com.example.simple-event-effective.ingest:de0ba1dd"
                }
              }
            ]
          },
          "_zen_clientid": {
            "scalars": [
              {
                "Value": {
                  "StringVal": "dCcYQMIIpi0e3JRhtH4MDSbAq9ItRRP3"
                }
              }
            ]
          },
          "_zen_direct_entity_id": {
            "scalars": [
              {
                "Value": {
                  "StringVal": "AAAAA53hEnMFlJGP7yjZG4BpZbs="
                }
              }
            ]
          },
          "_zen_entityIds": {
            "scalars": [
              {
                "Value": {
                  "StringVal": "AAAAA53hEnMFlJGP7yjZG4BpZbs="
                }
              }
            ]
          }
        },
        "summary": "Event created for entity one",
        "severity": 5,
        "status": 1
      }
    }
  }
}