Recipients API | Honeycomb

We use cookies or similar technologies to personalize your online experience & tailor marketing to you. Many of our product features require cookies to function properly.

Read our privacy policy I accept cookies from this site

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?