Recipients

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

The types of Recipients supported are: PagerDuty, Email, Webhook, Microsoft Teams, and Slack.

Authorization

The API key must have the Manage Recipients permission. Recipients are team-wide and NOT environment-specific. API Keys with the Manage Recipients permission can modify recipients used by ALL environments for a given team.

Learn more about API keys here.

Create a Recipient

Unlike many resources, Recipients are not linked to a specific Environment or Dataset. The Recipient will be created for the Team associated with your API key.

The details fields will vary depending on the type of Recipient. Use the drop-down to view the specific fields for each type value.

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

Securityconfiguration_key
Request
Request Body schema: application/json
required
type
string

One of the supported Recipient Types

object

Specific schema for the Pagerduty Recipient Type

Responses
201

Success

400

The provided request body was invalid. Most APIs will return a DetailedError for this condition, explaining what went wrong, but some older APIs only return a GenericError.

401

Unauthorized

403

Forbidden

409

Conflict

422

Validation Failed

post/1/recipients
Request samples
application/json
{
  • "type": "pagerduty",
  • "details": {
    }
}
Response samples
application/json
{
  • "id": "yUheCUmgZ8p",
  • "created_at": "2022-07-26T22:38:04Z",
  • "updated_at": "2022-07-26T22:38:04Z",
  • "type": "pagerduty",
  • "details": {
    }
}

List all Recipients

Retrieve all recipients for a team.

Securityconfiguration_key
Responses
200

Success

401

Unauthorized

get/1/recipients
Request samples
Response samples
application/json
[
  • {
    }
]

Get a single Recipient

Retrieve a Recipient by recipient ID.

Securityconfiguration_key
Request
path Parameters
recipientId
required
string

Unique identifier (ID) of a Recipient.

Responses
200

Success

401

Unauthorized

404

Not Found

get/1/recipients/{recipientId}
Request samples
Response samples
application/json
{
  • "id": "yUheCUmgZ8p",
  • "created_at": "2022-07-26T22:38:04Z",
  • "updated_at": "2022-07-26T22:38:04Z",
  • "type": "pagerduty",
  • "details": {
    }
}

Update a Recipient

Update a Recipient by specifying the recipient ID and full recipient details. (Partial PUT is not supported.)

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

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

Securityconfiguration_key
Request
path Parameters
recipientId
required
string

Unique identifier (ID) of a Recipient.

Request Body schema: application/json
required
type
string

One of the supported Recipient Types

object

Specific schema for the Pagerduty Recipient Type

Responses
200

Success

401

Unauthorized

404

Not Found

409

Conflict

422

Validation Failed

put/1/recipients/{recipientId}
Request samples
application/json
{
  • "type": "pagerduty",
  • "details": {
    }
}
Response samples
application/json
{
  • "id": "yUheCUmgZ8p",
  • "created_at": "2022-07-26T22:38:04Z",
  • "updated_at": "2022-07-26T22:38:04Z",
  • "type": "pagerduty",
  • "details": {
    }
}

Delete a Recipient

Delete a recipient by specifying the recipient ID.

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

Securityconfiguration_key
Request
path Parameters
recipientId
required
string

Unique identifier (ID) of a Recipient.

Responses
204

Success - no content

401

Unauthorized

404

Not Found

409

Conflict

delete/1/recipients/{recipientId}
Request samples
Response samples
application/json
{
  • "error": "unknown API key - check your credentials"
}