We use cookies or similar technologies to personalize your online experience and tailor marketing to you. Many of our product features require cookies to function properly. Your use of this site and online product constitutes your consent to these personalization technologies. Read our Privacy Policy to find out more.

X

Triggers API

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.

Fields on a Trigger

A Trigger consists of a name, description, associated Honeycomb query (which must contain one calculation), threshold, and list of one or more recipients.

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 belong to Datasets, and the Dataset name is encoded in the REST URL for each action.

Headers

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.

Create a Trigger

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":[
    {
      "type":"email",
      "target":"alerts@example.com"
    },
    {
      "type":"slack",
      "target":"#alerts"
    },
    {
      "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"
  },
  "frequency":900,
  "threshold":{"op":">","value":0},
  "recipients":[
    {
      "type":"email",
      "target":"alerts@example.com"
    },
    {
      "type":"slack",
      "target":"#alerts"
    },
    {
      "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.

Retrieve a Trigger

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/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"
  },
  "threshold": { "op": ">", "value": 0 },
  "recipients": [
    {
      "type": "email",
      "target": "alerts@example.com"
    },
    {
      "type": "slack",
      "target": "#alerts"
    },
    {
      "type": "pagerduty"
    }
  ],
  "id": "FjQTTZKe5sC"
}

Update a Trigger

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"
  },
  "frequency":600,
  "threshold":{"op":">","value":1},
  "recipients":[
    {
      "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"
  },
  "frequency": 600,
  "threshold": { "op": ">", "value": 1 },
  "recipients": [
    {
      "type": "email",
      "target": "alerts@example.com"
    }
  ],
  "id": "FjQTTZKe5sC"
}

Delete a Trigger

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/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.

List all Triggers

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.