The Triggers API is for creating, reading, modifying, or deleting Honeycomb Triggers via API.
All requests should be made via HTTPS to api.honeycomb.io.
The API is permitted to manipulate Triggers as if it was any other member of your team. (See our Roles and Permissions for more details.)
To see an example of the Triggers API in action, try out the Webhook Listener Example App.
A Trigger consists of a name, description, associated Honeycomb query (which must contain one calculation), threshold, and list of one or more recipients.
Use the optional alert_type field with one of the following values to determine the trigger’s mode of operation for your use case:
on_change: (default) Sends a trigger notification when the result of the specified calculation crosses the threshold. The trigger resolves only when the result of the query no longer satisfies the threshold condition.on_true: Keep sending a trigger notification at current frequency when and while the threshold is being met. (This reflects the same behavior as the “Send an alert every time a threshold is met” checkbox in the Honeycomb UI.)Triggers have a duration over which they query data and a frequency which determines how often they run. A trigger with a duration of 5 minutes (set query time_range to 300) and a frequency of 2 minutes will run every 2 minutes over the last 5 minutes of data. The duration of a trigger query can be at most 1 day, and cannot exceed 4 times the frequency of the trigger. For example, if the trigger’s frequency is 1 hour, query duration can not be more than 4 hours. Query duration can also not be less than the trigger’s frequency.
Triggers belong to Datasets, and the Dataset name is encoded in the REST URL for each action.
name: (required) the trigger’s name displayed in the UI
description: displayed on the triggers page itself
disabled: a boolean for the disabled state of the trigger. If true, the trigger will not be run. If this field is omitted, the trigger will be enabled (i.e. disabled = false)
query_id or query: (required) a query ID or an inline query that is a strict subset of a Query Specification. A Trigger Query Specification must contain exactly one item in calculations, and may contain breakdowns, filters, and/or filter_combination, and time_range, which defines the query’s duration. The HEATMAP calculation may not be used for the trigger calculation. time_range will default to frequency if frequency is specified, or to 900 seconds (15 min, the default for frequency) if frequency is not specified
threshold: (required) an object with a specified Filter "op" and a "value" against which to compare the result. Allowed threshold "op"s are >, >=, <, and <=.
frequency: an integer describing the interval (in seconds) in which to check the results of the query’s calculation against the threshold. Value must be divisible by 60 and between 60 and 86400 (between 1 minute and 1 day). Defaults to 900 (15 minutes).
alert_type: a string value defining when to fire the alert. Allowed values for "alert_type" are on_change (default) and on_true (continuously fires when threshold is met)
evaluation_schedule_type: a string value that determines what type of schedule the trigger uses. Allowed values are frequency (the default, which runs the trigger on the provided frequency) and window (which runs the trigger on the provided frequency only within a specified time window). The time window is specified in the evaluation_schedule field.
evaluation_schedule: an object that describes the time frame in which the trigger should be run. This field is only allowed if evaluation_schedule_type is set to window. See below for the format of this field.
recipients: a list of Recipients to notify when a given Trigger fires.
Recipients can be created and managed via the Recipients API.
To use an existing recipient, it is recommended to specify the recipient by ID.
The type and target are NOT required when specifying the Recipient ID.
triggered: a boolean indicating whether this trigger crossed its specified threshold without resolving. If true, the trigger crossed its specified threshold without resolving. (This triggered field is present in responses only, and will be ignored in requests.)
Triggers can be set to run during a particular window of time. This is done by specifying the days of the week to run the trigger as well as a start and end time. All days and times are UTC and use 24-hour time format.
{
"name":"Unusual activity during business hours",
"query_id": "abc3419d",
"frequency":900,
"threshold":{"op":">","value":0},
"disabled":false,
"alert_type":"on_change",
"id":"FjQTTZKe5sC",
"triggered":"false",
"evaluation_schedule_type": "window",
"evaluation_schedule": {
"window": {
"days_of_week": ["monday", "tuesday", "wednesday", "thursday", "friday"],
"start_time": "09:00",
"end_time": "17:00"
}
}
}
The start time will always be during the days of the week specified. However, if you specify an end time that is the same as or less than the start time (for example, “09:00” to “07:00”), the end time will be set the day after the start time. The length of time between the start and end time must be at least twice the frequency of the trigger (for example, a 15-minute trigger must have a start and end time that are at least 30 minutes apart). Triggers are not guaranteed to run at the start of the time window provided.
For example, with the following schedule:
{
"window": {
"days_of_week": ["monday", "tuesday"],
"start_time": "21:00",
"end_time": "03:00"
}
}
The trigger would run from 9 PM UTC on Monday until 3 AM UTC Tuesday and also from 9 PM UTC on Tuesday until 3 AM UTC Wednesday.
The only expected header is X-Honeycomb-Team, which is your API key, and it is required.
The API key must have the Manage Triggers permission.
Learn more about API keys.
Recipients can be created and managed via the Recipients APIs.
To use existing recipients with your triggers, it is best to specify the recipient using the recipient’s unique ID. There are a few options to get a recipient’s ID via an API:
If a recipient is passed with only the type and target included but no ID, Honeycomb will make a best effort to match to an existing recipient.
If specifying by type and target, type must be one of the following values: email, slack, pagerduty, or webhook.
PagerDuty recipients can also include a details object with a pagerduty_severity attribute.
Valid severity values are critical, error, warning, or info.
If pagerduty_severity is not included, the severity will default to critical.
Triggers are created by sending a POST request to /1/triggers/<DATASET_NAME>.
The body of the POST should be a JSON encoded object containing key/value pairs.
ID may not be set during creation.
A successful response will return HTTP 201 and the Location header will contain the URL to the new Trigger resource.
Invalid input will result in a HTTP 422 being returned.
curl https://api.honeycomb.io/1/triggers/DATASET_NAME -X POST \
-H "X-Honeycomb-Team: YOUR_API_KEY" \
-d '
{
"name":"Unusual endpoint access",
"query":{
"breakdowns":["user_agent"],
"calculations":[{"op": "COUNT"}],
"filters":[
{"column":"endpoint","op":"=","value":"/wp-login.php"},
{"column":"endpoint","op":"=","value":"/.htaccess"}
],
"filter_combination": "OR"
},
"threshold":{"op":">","value":0},
"alert_type":"on_change",
"disabled":false,
"recipients":[
{
"id": "abcd123",
"type":"email",
"target":"alerts@example.com"
},
{
"id": "efghij4",
"type":"slack",
"target":"#alerts"
},
{
"id": "b4Z71h",
"type":"pagerduty",
"details": {
"pagerduty_severity": "error"
}
}
]
}'
{
"name":"Unusual endpoint access",
"query_id": "abc3419d",
"frequency":900,
"threshold":{"op":">","value":0},
"disabled":false,
"alert_type":"on_change",
"recipients":[
{
"id": "abcd123",
"type":"email",
"target":"alerts@example.com"
},
{
"id": "efghij4",
"type":"slack",
"target":"#alerts"
},
{
"id": "b4Z71h",
"type":"pagerduty",
"details": {
"pagerduty_severity": "error"
}
}
],
"id":"FjQTTZKe5sC",
"triggered":"false"
}'
Fetch details for a single Trigger by sending a GET request to /1/triggers/<DATASET_NAME>/<Trigger ID>.
curl https://api.honeycomb.io/1/triggers/DATASET_NAME/FjQTTZKe5sC \
-H "X-Honeycomb-Team: YOUR_API_KEY"
{
"name": "Unusual endpoint access",
"description": "(watch out for h4ck3rz)",
"frequency": 900,
"query_id": "abc3419d",
"threshold": { "op": ">", "value": 0 },
"disabled": true,
"alert_type": "on_change",
"recipients": [
{
"id": "abcd123",
"type": "email",
"target": "alerts@example.com"
},
{
"id": "efghij4",
"type": "slack",
"target": "#alerts"
},
{
"id": "b4Z71h",
"type": "pagerduty",
"details": {
"pagerduty_severity": "error"
}
}
],
"id": "FjQTTZKe5sC",
"triggered": "false"
}
Update a specific Trigger directly by sending a PUT request to /1/triggers/<DATASET_NAME>/<Trigger ID>.
The body of the request must contain the same fields as for creating a new trigger. Missing (optional) fields will use the defaults, not existing values.
Note for the disabled field:
The disabled field has special behavior for PUT requests. If omitted, Honeycomb will keep the current value of the disabled field. In other words, if your trigger is disabled and you send a PUT request with the disabled field omitted from the json payload, the trigger will remain disabled.
curl https://api.honeycomb.io/1/triggers/DATASET_NAME/FjQTTZKe5sC -X PUT \
-H "X-Honeycomb-Team: YOUR_API_KEY" \
-d '
{
"name":"Unusual endpoint access",
"description":"(watch out for h4ck3rz)",
"query_id": "abc3419d",
"frequency":600,
"threshold":{"op":">","value":1},
"disabled": true,
"alert_type":"on_change",
"recipients":[
{
"id": "abcd123",
"type":"email",
"target":"alerts@example.com"
}
]
}'
{
"name": "Unusual endpoint access",
"description": "(watch out for h4ck3rz)",
"query_id": "abc3419d",
"frequency": 600,
"threshold": { "op": ">", "value": 1 },
"alert_type": "on_change",
"disabled": true,
"recipients": [
{
"id": "abcd123",
"type": "email",
"target": "alerts@example.com"
}
],
"id": "FjQTTZKe5sC",
"triggered": "false"
}
Delete a specific Trigger for a Dataset by sending a DELETE request to /1/triggers/<DATASET_NAME>/<Trigger ID>.
The body of the DELETE request should be empty.
A successful DELETE response will return a HTTP 204 status code.
curl https://api.honeycomb.io/1/triggers/DATASET_NAME/2NeeaE9bBLd -X DELETE \
-H "X-Honeycomb-Team: YOUR_API_KEY"
# DELETE returns HTTP 204: No Content
All the Triggers in a dataset may be retrieved by sending a GET request to /1/triggers/<DATASET_NAME>.
A successful response will return HTTP 200 and a JSON list of all Trigger objects for the dataset.
Invalid input will result in a HTTP 422 being returned.
curl https://api.honeycomb.io/1/triggers/DATASET_NAME \
-X GET -H "X-Honeycomb-Team: YOUR_API_KEY"
Did you find what you were looking for?