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.
This feature is not available in Honeycomb’s Community Edition.
A Trigger consists of a name
, description
, associated Honeycomb query (which must contain one calculation), threshold
, and list of one or more recipient
s.
Triggers fire when the result of the specified calculation crosses the specified threshold; they resolve when the result of the query no longer satisfies the threshold condition.
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 UIdescription
: displayed on the triggers page itselfquery
: (required) 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. time_range
will default to frequency
if frequency
is specified, or to 900 seconds (15 min, the default for frequency
) if frequency
is not specifiedthreshold
: (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).recipients
: a list of Recipients to notify when a given Trigger fires. Pagerduty and Slack recipients must be configured in the UI before they can be used via an API request. If you would like to use an existing recipient, it is recommended (although not required) to specify the recipient using its id.Note for Honeycomb Secure Tenancy users:
Trigger names and descriptions will not be masked by the secure proxy. Please only use names and descriptions that you feel comfortable storing in Honeycomb’s database and sending through third parties such as Slack or PagerDuty.
The only expected header is X-Honeycomb-Team
, which is your Team API key. It is required.
Triggers are considered a separate resource from our Events, Markers, or Boards APIs.
To use this API, you may want to modify an existing API key to be able to access Triggers or create a new Triggers-only key.
To use existing recipients with your triggers (e.g. you are creating a new trigger and you’d like to assign a webhook you’ve setup previously in the Integration Center), it is best to specify the recipient with its unique ID. If you pass in a recipient without its ID and only include the type and target, Honeycomb will make a best effort to match to an existing recipient.
To get a recipient’s ID, it must have been previously used with a trigger. Run the List Triggers or Get Trigger API to get the JSON output for the trigger. It will include the recipient’s ID. Use that ID to specify the recipient.
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.
Example Request
$ 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},
"recipients":[
{
"id": "abcd123",
"type":"email",
"target":"alerts@example.com"
},
{
"id": "efghij4",
"type":"slack",
"target":"#alerts"
},
{
"id": "b4Z71h",
"type":"pagerduty"
}
]
}'
Example Response
{
"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",
"time_range": 900,
},
"frequency":900,
"threshold":{"op":">","value":0},
"recipients":[
{
"id": "abcd123",
"type":"email",
"target":"alerts@example.com"
},
{
"id": "efghij4",
"type":"slack",
"target":"#alerts"
},
{
"id": "b4Z71h",
"type":"pagerduty"
}
],
"id":"FjQTTZKe5sC"
}'
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.
Fetch details for a single Trigger by sending a GET
request to /1/triggers/<DATASET_NAME>/<Trigger ID>
Example Request
curl https://api.honeycomb.io/1/triggers/DATASET_NAME/FjQTTZKe5sC \
-H "X-Honeycomb-Team: YOUR_API_KEY"
Example Response
{
"name": "Unusual endpoint access",
"frequency": 900,
"query": {
"breakdowns": ["user_agent"],
"calculations": [{ "op": "COUNT" }],
"filters": [
{ "column": "endpoint", "op": "=", "value": "/wp-login.php" },
{ "column": "endpoint", "op": "=", "value": "/.htaccess" }
],
"filter_combination": "OR",
"time_range": 900
},
"threshold": { "op": ">", "value": 0 },
"recipients": [
{
"id": "abcd123",
"type": "email",
"target": "alerts@example.com"
},
{
"id": "efghij4",
"type": "slack",
"target": "#alerts"
},
{
"id": "b4Z71h",
"type": "pagerduty"
}
],
"id": "FjQTTZKe5sC"
}
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.
Example Request
$ 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":{
"breakdowns":["user_agent"],
"calculations":[{"op": "COUNT"}],
"filters":[
{"column":"endpoint","op":"=","value":"/wp-login.php"},
{"column":"endpoint","op":"=","value":"/.htaccess"},
{"column":"endpoint","op":"=","value":"/.htpasswd"}
],
"filter_combination": "OR",
"time_range": 1200,
},
"frequency":600,
"threshold":{"op":">","value":1},
"recipients":[
{
"id": "abcd123",
"type":"email",
"target":"alerts@example.com"
}
]
}'
Example Response
{
"name": "Unusual endpoint access",
"description": "(watch out for h4ck3rz)",
"query": {
"breakdowns": ["user_agent"],
"calculations": [{ "op": "COUNT" }],
"filters": [
{ "column": "endpoint", "op": "=", "value": "/wp-login.php" },
{ "column": "endpoint", "op": "=", "value": "/.htaccess" },
{ "column": "endpoint", "op": "=", "value": "/.htpasswd" }
],
"filter_combination": "OR",
"time_range": 1200
},
"frequency": 600,
"threshold": { "op": ">", "value": 1 },
"recipients": [
{
"id": "abcd123",
"type": "email",
"target": "alerts@example.com"
}
],
"id": "FjQTTZKe5sC"
}
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.
Example Request
$ curl https://api.honeycomb.io/1/triggers/DATASET_NAME/2NeeaE9bBLd -X DELETE \
-H "X-Honeycomb-Team: YOUR_API_KEY"
Example Response
# DELETE returns HTTP 204: No Content
A successful DELETE
response will a HTTP 204
status code.
All the Triggers in a dataset may be retrieved by sending a GET
request to /1/triggers/<DATASET_NAME>
Example Request
$ curl https://api.honeycomb.io/1/triggers/DATASET_NAME \
-X GET -H "X-Honeycomb-Team: YOUR_API_KEY"
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.