Working with Recipients

Recipients define where to send notifications when triggers fire. Supported types include email, Slack, PagerDuty, webhooks, and MS Teams.

Basic Recipient Operations

List Recipients

AsyncSync

async def list_all_recipients(client: HoneycombClient) -> list[Recipient]:
    """List all recipients in the environment.

    Returns:
        List of all recipients
    """
    recipients = await client.recipients.list_async()
    for recipient in recipients:
        print(f"{recipient.type}: {recipient.id}")
    return recipients

def list_all_recipients_sync(client: HoneycombClient) -> list[Recipient]:
    """List all recipients using sync client.

    Returns:
        List of all recipients
    """
    recipients = client.recipients.list()
    for recipient in recipients:
        print(f"{recipient.type}: {recipient.id}")
    return recipients

Get, Update, Delete Recipients

All standard CRUD operations are available:

# Get recipient
recipient = await client.recipients.get_async(recipient_id)

# Update recipient
updated = await client.recipients.update_async(
    recipient_id,
    RecipientCreate(type=RecipientType.EMAIL, details={"email_address": "new@example.com"})
)

# Delete recipient
await client.recipients.delete_async(recipient_id)

# Find which triggers use this recipient
triggers = await client.recipients.get_triggers_async(recipient_id)

Creating Recipients

Email Recipient

With RecipientBuilderManual Construction

async def create_email_recipient(client: HoneycombClient) -> str:
    """Create an email recipient using RecipientBuilder.

    Returns:
        The created recipient ID
    """
    recipient = RecipientBuilder.email("alerts@example.com")
    created = await client.recipients.create_async(recipient)
    return created.id

async def create_email_recipient_manual(client: HoneycombClient) -> str:
    """Create an email recipient using manual construction.

    Returns:
        The created recipient ID
    """
    recipient = EmailRecipient(
        type="email",
        details={"email_address": "alerts@example.com"},
    )
    created = await client.recipients.create_async(recipient)
    return created.id

Webhook Recipient

Basic WebhookWith Authentication HeadersWith Custom Payload Templates

async def create_webhook_recipient(client: HoneycombClient) -> str:
    """Create a webhook recipient using RecipientBuilder.

    Returns:
        The created recipient ID
    """
    recipient = RecipientBuilder.webhook(
        url="https://your-webhook.example.com/alerts",
        name="Custom Webhook",
        secret="optional-secret-for-validation",
    )
    created = await client.recipients.create_async(recipient)
    return created.id

async def create_webhook_with_auth_headers(client: HoneycombClient) -> str:
    """Create a webhook recipient with authentication headers.

    Useful for webhooks that require API keys or bearer tokens for authentication.

    Returns:
        The created recipient ID
    """
    recipient = RecipientBuilder.webhook(
        url="https://api.example.com/notifications",
        name="Authenticated Webhook",
        headers=[
            {"header": "Authorization", "value": "Bearer api-key-xyz123"},
            {"header": "X-Environment", "value": "production"},
        ],
    )
    created = await client.recipients.create_async(recipient)
    return created.id

async def create_webhook_with_custom_payload(client: HoneycombClient) -> str:
    """Create a webhook recipient with custom payload templates.

    Advanced feature for customizing the JSON payload sent to the webhook
    using template variables.

    Returns:
        The created recipient ID
    """
    recipient = RecipientBuilder.webhook(
        url="https://your-webhook.example.com/alerts",
        name="Custom Payload Webhook",
        template_variables=[
            {"name": "environment", "default_value": "production"},
            {"name": "severity", "default_value": "warning"},
        ],
        payload_templates={
            "trigger": {
                "body": '{"env": "{{.environment}}", "level": "{{.severity}}", "type": "trigger"}'
            },
            "budget_rate": {
                "body": '{"env": "{{.environment}}", "level": "critical", "type": "budget_rate"}'
            },
            "exhaustion_time": {
                "body": '{"env": "{{.environment}}", "level": "critical", "type": "exhaustion_time"}'
            },
        },
    )
    created = await client.recipients.create_async(recipient)
    return created.id

Recipient Types Reference

Basic Details Structure

Type	Required Fields	Optional Fields
EMAIL	email_address	-
SLACK	slack_channel	-
PAGERDUTY	pagerduty_integration_key (32 chars), pagerduty_integration_name	-
WEBHOOK	webhook_url, webhook_name	webhook_secret, webhook_headers, webhook_payloads
MSTEAMS_WORKFLOW	webhook_url, webhook_name	-
MSTEAMS	(deprecated, use MSTEAMS_WORKFLOW)	-

Webhook Advanced Features

HTTP Headers (max 5):

webhook_headers=[
    {"header": "Authorization", "value": "Bearer token"},
    {"header": "X-Custom-Header", "value": "custom-value"}
]

Payload Templates (for customizing webhook JSON):

# Define template variables
template_variables=[
    {"name": "environment", "default_value": "production"},
    {"name": "severity", "default_value": "warning"}
]

# Define payload templates for each alert type (trigger, budget_rate, exhaustion_time)
payload_templates={
    "trigger": {"body": '{"env": "{{.environment}}", "level": "{{.severity}}"}'},
    "budget_rate": {"body": '{"env": "{{.environment}}", "level": "critical"}'},
    "exhaustion_time": {"body": '{"env": "{{.environment}}", "level": "critical"}'}
}

# Use in RecipientBuilder
RecipientBuilder.webhook(
    url="https://example.com/webhook",
    template_variables=template_variables,
    payload_templates=payload_templates
)

Template Variable Syntax: Uses Go template syntax with dot prefix: {{.variableName}}

For complete webhook template reference, see Honeycomb's documentation: - Webhook Template Variables - All available variables for triggers and burn alerts - Webhook Template Functions - Functions like toJson, date, upper, join, etc. - Example Webhook Templates - Complete examples for Discord, Slack, incident.io, etc.

RecipientBuilder provides static factory methods: .email(), .slack(), .pagerduty(), .webhook(), .msteams()

Sync Usage

All recipient operations have sync equivalents:

with HoneycombClient(api_key="...", sync=True) as client:
    # List recipients
    recipients = client.recipients.list()

    # Create recipient
    recipient = client.recipients.create(
        RecipientCreate(type=RecipientType.EMAIL, details={"email_address": "team@example.com"})
    )

    # Get, update, delete recipient
    recipient = client.recipients.get(recipient_id)
    updated = client.recipients.update(recipient_id, RecipientCreate(...))
    client.recipients.delete(recipient_id)

    # Find triggers using this recipient
    triggers = client.recipients.get_triggers(recipient_id)