logo

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"
}
➔ Next to SLOs