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

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

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

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, 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

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 example

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

All destinationsEmailSlackWebhook

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

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

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