Recipients API | Honeycomb

Honeycomb.io Documentation
  1. Docs
  2. API
  3. Recipients API

Recipients API

Honeycomb Recipients allow you to define and manage the Recipients that will get notified by a Trigger or Burn Alert.

Recipients are also configurable via the Honeycomb UI by going to the Team’s Integration Center.

The types of Recipients supported are: PagerDuty, Email, Webhook, and Slack. This page contains information on creating and managing various Recipient Types via API.

Authorization and Headers 

The only expected header is X-Honeycomb-Team, which is your API key, and it is required. The API key must have the Manage Recipients permission. Learn more about API keys.

Recipients are team wide and NOT environment specific.

API Keys with the “Manage Recipients” permissions can modify recipients used by ALL environments for a given team.

Fields on a Recipient 

A Recipient consists of:

  • id: (Read Only) (string)
  • type: (required) (string) one of the supported Recipient Types [ email, slack, pagerduty, webhook ]
  • details: (required) (object) specific schema per Recipient Type
    • pagerduty_integration_name: (string) required for PagerDuty
    • pagerduty_integration_key: (string) required for PagerDuty
    • slack_channel: (string) required for Slack
    • webhook_name: (string) required for Webhook
    • webhook_url: (string) required for Webhook
    • webhook_secret: (string) required for Webhook
    • email_address: (string) required for Email

Create A Recipient 

A Recipient can be created by sending a POST request to /1/recipients/. The Recipient will be created for the Team associated with your API key.

The body of the POST should be a JSON encoded object containing key/value pairs. ID cannot not be set during creation.

Invalid input will result in a HTTP 422 being returned.

Create Example Request 

Each Recipient type requires certain details to be provided to create the Recipient. Below are the required details for each supported type.

Create Example Request - Email  

curl https://api.honeycomb.io/1/recipients/ -X POST \
    -H "X-Honeycomb-Team: YOUR_API_KEY" \
    -d '
{
  "type": "email",
  "details": {
    "email_address": "example@honeycomb.io"
  }
}'

Create Example Request - PagerDuty  

curl https://api.honeycomb.io/1/recipients/ -X POST \
    -H "X-Honeycomb-Team: YOUR_API_KEY" \
    -d '
{
  "type": "pagerduty",
  "details": {
    "pagerduty_integration_name": "Example PagerDuty Service",
    "pagerduty_integration_key": "test-pagerduty-integration-key"
  }
}'

Create Example Request - Slack 

Before Slack recipients can be created, the Slack OAuth flow in the Integration Center must be completed.

curl https://api.honeycomb.io/1/recipients/ -X POST \
    -H "X-Honeycomb-Team: YOUR_API_KEY" \
    -d '
{
  "type": "slack",
  "details": {
    "slack_channel": "#alerts-channel"
  }
}'

Create Example Request - Webhooks  

curl https://api.honeycomb.io/1/recipients/ -X POST \
    -H "X-Honeycomb-Team: YOUR_API_KEY" \
    -d '
{
  "type": "webhook",
  "details": {
    "webhook_name": "Example webhook",
    "webhook_url": "http://webhook.example.com",
    "webhook_secret": "this-is-a-secret"
  }
}'

Create Example Response 

Create Example Response: Success 

A successful response will return the Recipient ID along with the created_at and updated_at timestamps with the requested Recipient type and details.

201 Created
{
  "id": "someID",
  "type": "email",
  "details": {
    "email_address": "example@honeycomb.io"
  },
  "created_at": "2022-05-11T09:53:04-07:00",
  "updated_at": "2022-05-11T09:53:04-07:00"
}

Create Example Response: Error Unsupported Type  

422 Unprocessable Entity
{
  "status": 422,
  "type": "https://api.honeycomb.io/problems/validation-failed",
  "title": "The provided input is invalid.",
  "type_detail": [
    {
      "field": "type",
      "code": "invalid",
      "description": "type: must be a valid value"
    }
  ],
  "error": "The provided input is invalid."
}

Get a Recipient 

A Recipient can be retrieved by sending a GET request to /1/recipients/{recipient-id}.

Get Example Request  

curl https://api.honeycomb.io/1/recipients/{recipient-id} -X GET  \
    -H "X-Honeycomb-Team: YOUR_API_KEY"

Get Example Response 

Get Example Response: Success  

200 OK
{
  "id": "someID",
  "type": "email",
  "details": {
    "email_address": "example@honeycomb.io"
  },
  "created_at": "2022-05-11T09:53:04-07:00",
  "updated_at": "2022-05-11T09:53:04-07:00"
}

Get Example Response: Error Recipient ID Does not Exist  

404 Not Found
{
    "status": 404,
    "type": "https://api.honeycomb.io/problems/not-found",
    "title": "The requested resource cannot be found.",
    "error": "The requested resource cannot be found."
}

Update a Recipient 

A Recipient can be updated by sending a PUT request to /1/recipients/{recipient-id}.

Modifying an existing recipient will change the destination of all triggers/burn alerts that use that recipient.

The body of the PUT should be a JSON encoded object containing key/value pairs. Same schema as the CREATE Recipient requests per Recipient Type.

Invalid input will result in a HTTP 422 being returned. If the edit request is attempting to duplicate an existing Recipient a 409 will be returned.

Updates to the Recipient Type is not supported. For example, changing an existing Recipient from PagerDuty to Email is not allowed.

Update Example Request  

curl https://api.honeycomb.io/1/recipients/t2xbD5vNhh1 -X PUT \
    -H "X-Honeycomb-Team: YOUR_API_KEY" \
    -d '
{
  "type": "pagerduty",
  "details": {
    "pagerduty_integration_name": "string",
    "pagerduty_integration_key": "string"
  }
}'

Update Example Response 

Update Example Response: Success  

201 Created
{
  "id": "someID",
  "type": "pagerduty",
  "details": {
    "pagerduty_integration_name": "Example PagerDuty Service",
    "pagerduty_integration_key": "test-pagerduty-integration-key"
  },
  "created_at": "2022-05-11T09:53:04-07:00",
  "updated_at": "2022-05-11T09:53:04-07:00"
}

Update Example Response: Error Conflict  

409 Conflict
{
  "status": 409,
  "type": "https://api.honeycomb.io/problems/conflict",
  "title": "Request could not be completed due to a conflict with the current state of the target resource.",
  "detail": "Recipient of type \"pagerduty\" already exists with the details provided.",
  "error": "Recipient of type \"pagerduty\" already exists with the details provided."
}

Delete a Recipient 

A Recipient can be deleted (permanently) by sending a DELETE request to /1/recipients/{recipient-id}.

A Recipient can only be deleted if it is NOT in use by any Triggers or Burn Alerts associated to the team.

Delete Example Request  

curl https://api.honeycomb.io/1/recipients/{recipient-id} -X DELETE  \
    -H "X-Honeycomb-Team: YOUR_API_KEY"

Delete Example Response 

Delete Example Response: Success  

204 No Content

Delete Example Response: Error Recipient ID does not exist  

404 Not Found
{
    "status": 404,
    "type": "https://api.honeycomb.io/problems/not-found",
    "title": "The requested resource cannot be found.",
    "error": "The requested resource cannot be found."
}

Delete Example Response: Error Recipient in use by a Trigger or Burn Alert  

409 Conflict
{
  "status": 409,
  "type": "https://api.honeycomb.io/problems/conflict",
  "title": "Request could not be completed due to a conflict with the current state of the target resource.",
  "detail": "Recipient 636NFxFqMgo is being used by a trigger or burn alert and cannot be deleted",
  "error": "Recipient 636NFxFqMgo is being used by a trigger or burn alert and cannot be deleted"
}

Get ALL Recipients for a Team 

All Recipients that are configured for a Team can be retrieved by sending a GET request to /1/recipients/.

This will return ALL Recipients configured with details used, once used or un-used by Triggers and Burn Alerts.

Get Example Request  

curl https://api.honeycomb.io/1/recipients/ -X GET  \
    -H "X-Honeycomb-Team: YOUR_API_KEY"

Get Example Response 

Get Example Response: Success  

200 OK
[
  {
    "id": "someID",
    "type": "pagerduty",
    "details": {
      "pagerduty_integration_key": "test-pagerduty-integration-key",
      "pagerduty_integration_name": "Test Service"
    },
    "created_at": "2022-06-22T20:10:01Z",
    "updated_at": "2022-06-22T20:10:01Z"
  },
  {
    "id": "someID",
    "type": "email",
    "details": {
      "email_address": "alerts@alerts.com"
    },
    "created_at": "2020-05-26T20:21:56Z",
    "updated_at": "2020-05-26T20:21:56Z"
  },
  {
    "id": "someID",
    "type": "slack",
    "details": {
      "slack_channel": "#test"
    },
    "created_at": "2018-10-15T17:25:25Z",
    "updated_at": "2018-10-15T17:25:25Z"
  }
]

Get Triggers Associated with a Recipient 

All triggers associated with a specific recipient can be retrieved by sending a GET request to /1/recipients/{recipient-id}/triggers.

This request will return all Triggers associated with the specific Recipient ID across your entire Honeycomb team rather than being scoped to a dataset or environment.

Get Example Request  

curl https://api.honeycomb.io/1/recipients/t2xbD5vNhh1/triggers -X GET  \
    -H "X-Honeycomb-Team: YOUR_API_KEY"

Get Example Response 

Get Example Response: Success  

200 OK
[
  {
  "name": "trigger 1",
  "query_id": "abc3419d",
  "frequency": 600,
  "threshold": { "op": ">", "value": 1 },
  "alert_type": "on_change",
  "disabled": true,
  "recipients": [
    {
      "id": "t2xbD5vNhh1",
      "type": "email",
      "target": "alerts@example.com"
    }
  ],
  "id": "FjQTTZKe5sC",
  "triggered": "false"
  },
  {
  "name": "trigger 2",
  "query_id": "abc3419d",
  "frequency": 900,
  "threshold": { "op": ">", "value": 5 },
  "alert_type": "on_change",
  "disabled": true,
  "recipients": [
    {
      "id": "t2xbD5vNhh1",
      "type": "email",
      "target": "alerts@example.com"
    }
  ],
  "id": "EjyRWS9LhcS",
  "triggered": "false"
  }
]

Did you find what you were looking for?

Table of Contents