---
title: "Create a Recipient"
method: POST
path: "/1/recipients"
tags: ["Recipients"]
---

# Create a Recipient

`POST /1/recipients`

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.

## Request body

- union
  - object
    - `type` 'pagerduty', required — One of the supported Recipient Types
    - `id` string
    - `created_at` string, date-time — ISO8601 formatted time the Recipient was created.
    - `updated_at` string, date-time — ISO8601 formatted time the Recipient was updated.
    - `details` object — Specific schema for the Pagerduty Recipient Type
      - `pagerduty_integration_name` string, required — A name for this Integration.
      - `pagerduty_integration_key` string, required — Pagerduty Integration Key.
  - object
    - `type` 'email', required — One of the supported Recipient Types
    - `id` string
    - `created_at` string, date-time — ISO8601 formatted time the Recipient was created.
    - `updated_at` string, date-time — ISO8601 formatted time the Recipient was updated.
    - `details` object — Specific schema for the Email Recipient Type
      - `email_address` string, required — Email address to notify.
  - object
    - `type` 'slack', required — One of the supported Recipient Types
    - `id` string
    - `created_at` string, date-time — ISO8601 formatted time the Recipient was created.
    - `updated_at` string, date-time — ISO8601 formatted time the Recipient was updated.
    - `details` object — Specific schema for the Slack Recipient Type.
      - `slack_channel` string, required — Slack channel to notify.
  - object
    - `type` 'webhook', required — One of the supported Recipient Types
    - `id` string
    - `created_at` string, date-time — ISO8601 formatted time the Recipient was created.
    - `updated_at` string, date-time — ISO8601 formatted time the Recipient was updated.
    - `details` object — Specific schema for the Webhook Recipient Type
      - `webhook_headers` WebhookHeader[] — Custom headers for this webhook
        - `header` string, required
        - `value` string
      - `webhook_name` string, required — A name for this Integration.
      - `webhook_url` string, required — Webhook URL.
      - `webhook_secret` string — Webhook secret.
      - `webhook_payloads` object — Specify a custom webhook payload.
        - `template_variables` TemplateVariableDefinition[] — Custom variable definitions for this webhook
          - `name` string, required
          - `default_value` string
        - `payload_templates` object
          - `trigger` PayloadTemplate
            - `body` string
          - `budget_rate` PayloadTemplate
            - `body` string
          - `exhaustion_time` PayloadTemplate
            - `body` string
  - object
    - `type` 'msteams', required — One of the supported Recipient Types
    - `id` string
    - `created_at` string, date-time — ISO8601 formatted time the Recipient was created.
    - `updated_at` string, date-time — ISO8601 formatted time the Recipient was updated.
    - `details` object — Specific schema for the MS Teams Recipient Type. Now deprecated, please use the `msteams_workflow` type instead.
      - `webhook_name` string, required — A name for this recipient.
      - `webhook_url` string, required — Incoming webhook URL of an Teams instance.
  - object
    - `type` 'msteams_workflow', required — One of the supported Recipient Types
    - `id` string
    - `created_at` string, date-time — ISO8601 formatted time the Recipient was created.
    - `updated_at` string, date-time — ISO8601 formatted time the Recipient was updated.
    - `details` object — Specific schema for the MS Teams Workflow Recipient Type.
      - `webhook_name` string, required — A name for this recipient.
      - `webhook_url` string, required — Incoming webhook URL of an Teams instance.

## Response `201`

Success

- union
  - object
    - `type` 'pagerduty', required — One of the supported Recipient Types
    - `id` string
    - `created_at` string, date-time — ISO8601 formatted time the Recipient was created.
    - `updated_at` string, date-time — ISO8601 formatted time the Recipient was updated.
    - `details` object — Specific schema for the Pagerduty Recipient Type
      - `pagerduty_integration_name` string, required — A name for this Integration.
      - `pagerduty_integration_key` string, required — Pagerduty Integration Key.
  - object
    - `type` 'email', required — One of the supported Recipient Types
    - `id` string
    - `created_at` string, date-time — ISO8601 formatted time the Recipient was created.
    - `updated_at` string, date-time — ISO8601 formatted time the Recipient was updated.
    - `details` object — Specific schema for the Email Recipient Type
      - `email_address` string, required — Email address to notify.
  - object
    - `type` 'slack', required — One of the supported Recipient Types
    - `id` string
    - `created_at` string, date-time — ISO8601 formatted time the Recipient was created.
    - `updated_at` string, date-time — ISO8601 formatted time the Recipient was updated.
    - `details` object — Specific schema for the Slack Recipient Type.
      - `slack_channel` string, required — Slack channel to notify.
  - object
    - `type` 'webhook', required — One of the supported Recipient Types
    - `id` string
    - `created_at` string, date-time — ISO8601 formatted time the Recipient was created.
    - `updated_at` string, date-time — ISO8601 formatted time the Recipient was updated.
    - `details` object — Specific schema for the Webhook Recipient Type
      - `webhook_headers` WebhookHeader[] — Custom headers for this webhook
        - `header` string, required
        - `value` string
      - `webhook_name` string, required — A name for this Integration.
      - `webhook_url` string, required — Webhook URL.
      - `webhook_secret` string — Webhook secret.
      - `webhook_payloads` object — Specify a custom webhook payload.
        - `template_variables` TemplateVariableDefinition[] — Custom variable definitions for this webhook
          - `name` string, required
          - `default_value` string
        - `payload_templates` object
          - `trigger` PayloadTemplate
            - `body` string
          - `budget_rate` PayloadTemplate
            - `body` string
          - `exhaustion_time` PayloadTemplate
            - `body` string
  - object
    - `type` 'msteams', required — One of the supported Recipient Types
    - `id` string
    - `created_at` string, date-time — ISO8601 formatted time the Recipient was created.
    - `updated_at` string, date-time — ISO8601 formatted time the Recipient was updated.
    - `details` object — Specific schema for the MS Teams Recipient Type. Now deprecated, please use the `msteams_workflow` type instead.
      - `webhook_name` string, required — A name for this recipient.
      - `webhook_url` string, required — Incoming webhook URL of an Teams instance.
  - object
    - `type` 'msteams_workflow', required — One of the supported Recipient Types
    - `id` string
    - `created_at` string, date-time — ISO8601 formatted time the Recipient was created.
    - `updated_at` string, date-time — ISO8601 formatted time the Recipient was updated.
    - `details` object — Specific schema for the MS Teams Workflow Recipient Type.
      - `webhook_name` string, required — A name for this recipient.
      - `webhook_url` string, required — Incoming webhook URL of an Teams instance.

## Other responses

- `400` — The provided request body was invalid.
- `401` — Unauthorized
- `403` — Forbidden
- `409` — Conflict
- `422` — Validation Failed

---

[API](https://skmtc.net/honeycomb/apis/honeycomb-api.md) · [All operations](https://skmtc.net/honeycomb/apis/honeycomb-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/honeycomb/honeycomb-api/revisions/117619fac2a5/schema)