Skip to main content
The Webhooks + Honeycomb integration uses Honeycomb Triggers or Honeycomb Service Level Objective (SLO) Burn Alerts to notify an arbitrary webhook based on alerts sent from Honeycomb. Use to integrate with third parties that receive JSON payloads. A webhook can be any HTTP endpoint which accepts JSON that you want Honeycomb to send notification of a trigger or SLO’s changing state. Once configured, Honeycomb sends JSON payloads to your webhook upon alerts firing. The content will include an authentication header and the result of the alert in JSON in the body of the webhook. Honeycomb expects the webhook to respond within 10 seconds; if no response is received within this timeframe, the request will fail. You can customize your webhook in Honeycomb with functions and variables. View our available example webhook templates for inspiration. Refer to our API documentation for programmatic management of webhook notifications.

​
Before You Begin

Before you set up the integration, you’ll need a user account in your Honeycomb Team.

​
Set Up Your Integration

Before you can configure Honeycomb to send alerts to your webhook, you must set up your webhook integration.

​
Create a Webhook

To create a webhook:
  1. Navigate to Team Settings, and select the Integrations view.
  2. Locate Trigger and SLO Recipients, and select Add Integration.
  3. For Provider, select Webhook.
  4. Enter a Name. We recommend using a name that will be easy to find when configuring alerts in the future.
  5. Enter your Webhook URL, and optionally a Shared Secret for either:
    • an HTTP endpoint running within your infrastructure
    • the URL and headers needed by the target service to send alerts
  6. Optionally, customize your webhook by using the Payload, Variables, and/or Headers tabs.
  7. Select Add.

​
Configure Alerts to Use Your Webhook

After your webhook integration is set up in Honeycomb, you can configure Triggers and SLOs to use your webhook as a recipient for alerts.

​
Configure Triggers to Use Your Webhook

To configure Triggers to use your Webhook:
  1. In the Honeycomb UI, navigate to Triggers.
  2. Select the name of the existing trigger you want to configure, or create a new trigger by selecting New Trigger.
  3. Locate the Recipients section, and select Add Recipient.
  4. In the Add Trigger Recipient modal, locate the Recipient dropdown and select your webhook integration.
  5. Select Add.
  6. Select Save Trigger.

​
Configure SLO Burn Alerts to Use Your Webhook

To configure SLO Burn Alerts to use your webhook:
  1. In the Honeycomb UI, navigate to SLOs.
  2. Select the name of the existing SLO you want to configure, or create a new SLO by selecting New SLO.
  3. Find your SLO in the list, and select the Configure button in the Burn Alerts column.
  4. Select New Burn Alert.
  5. In the Create Burn Alert form:
    1. Set your desired exhaustion time.
    2. Select your webhook integration in the Notify dropdown.
    3. Set your desired Severity. (Critical is the default value.)
  6. Select Create Burn Alert.

​
Customize Your Webhook

Customizing your webhook integration allows for the tailoring your alert notifications for Triggers and SLOs to your needs. You can:
  • Customize Alert Content: Modify the structure and content of your alert payloads, including adding, removing, or reordering fields to meet the specific requirements of your target systems
  • Customize Alert Headers: Include relevant header keys and values accompanying the JSON payload. This allows you to integrate with services that expect specific HTTP header values
  • Include Alert-level Variable Support: Automatically include relevant alert context, such as the severity of the alert. This will allow you to pass critical context to your alert recipients without needing to manually customize each notification

​
Customize Webhook Payload

A webhook that uses custom payloads must have a corresponding payload for an alert type in order for it to be used with that alert type. For example, a webhook with only a configured Trigger payload cannot be used by an SLO Budget Rate Burn Alert. A webhook can have up to all three payload types configured. If no payload types are configured, then a webhook will operate as a standard webhook in Honeycomb. To customize your webhook payload:
  1. Within the webhook integration modal, navigate to the Payload tab.
  2. Toggle Enable next to each alert type to configure its payload. All three alert payload types - Triggers, (SLO) Budget Rate Burn, (SLO) Exhaustion Time Burn Alerts - can be enabled if desired. A text area will appear to enter a JSON template.
  3. Use the pre-configured Generic Webhook option or use the text area to further customize your JSON template. Refer to our template example documentation for inspiration.
  4. Optionally, you can configure and include custom variables and headers for use within your webhook.
  5. Select Add for new webhooks or Update for existing webhooks to complete the process.
Once saved, you can configure the Trigger or SLO Burn Alert to use your custom webhook.

​
Customize Webhook Variables

Webhooks with enabled custom payload templates may define up to 10 variables that can be referenced in the templates. Our custom payload variable documentation includes a list of available variables. Optionally, these variables can be overridden when configuring the webhook to a given Trigger or SLO Burn Alert.

​
Define Payload Template Variables

Webhooks with enabled custom payload templates may define up to 10 variables that can be referenced in the templates. Variables must first be defined in the Webhook integration:
  1. Navigate to Team Settings, and select the Integrations view.
  2. Locate Trigger and SLO Recipients.
  3. Create a new webhook or navigate to an existing webhook.
    1. If creating a new webhook, start the webhook creation process by selecting Add Integration and entering values.
    2. If editing an existing webhook, locate the desired Webhook integration in the list of integrations, and select Edit.
  4. In the modal, select the Variables tab.
  5. Select Add variable. You can add up to 10 variables.
  6. Enter a name for the variable. The variable name must:
    1. be alphanumeric
    2. be 64 characters or less
    3. begin with a lowercase letter
    4. be unique among all variables defined for this Webhook
  7. Optionally, enter a default value for the variable. This default value must be 256 characters or less.
Once defined, variables can be referenced in the payload template. For example, in a format similar to: 
{{ .Vars.severity }}

​
Override Payload Template Variables

Once defined in the Webhook integration, payload template variables may be overridden when using the Webhook integration with a Trigger or SLO Burn Alert. For example, you could define a severity variable, and give it a default value of warning. Then, when configuring an important Trigger, you could override that variable’s default value with a value of critical. When the Trigger fires, the value of the payload template variable will evaluate in the following order:
  • The override value for the variable, if it exists.
  • The default value for the variable, if it exists.
  • The empty string "".
Triggers
To override payload template variable(s) in a Trigger:
  1. In the Honeycomb UI, navigate to Triggers.
  2. Select the name of the trigger you want to configure, or create a new trigger by selecting New Trigger.
  3. Locate the Recipients section, and select Add Recipient.
  4. In the Add Trigger Recipient modal, locate the Recipient dropdown and select your webhook integration.
  5. All defined payload template variables for the selected webhook integration are displayed in rows.
  6. Locate the row for the variable you would like to override.
  7. Optionally, enter the override value for the variable in the “Value” text box. This override value must be 256 characters or less.
  8. Select Add.
  9. Select Save Trigger.
SLO Burn Alerts
To override payload template variable(s) in SLO Burn Alerts:
  1. In the Honeycomb UI, navigate to SLOs.
  2. In the list, locate the SLO you want to configure, or create a new SLO by selecting New SLO.
  3. Find your SLO in the list, and select the Configure button in the Burn Alerts column.
  4. Select New Burn Alert.
  5. In the Create Burn Alert form:
    1. Set your desired exhaustion time.
    2. Select your webhook integration in the Notify dropdown.
  6. Locate the target variable to override. All defined payload template variables for the selected webhook integration are displayed in rows.
  7. Optionally, enter the override value for the variable in the “Value” text box. This override value must be 256 characters or less.
  8. Select Create Burn Alert.

​
Customize Webhook Headers

When sending a notification to the specified webhook endpoint, Honeycomb will always include the following HTTP headers:
Header nameValue
Content-Typeapplication/json
User-AgentHoneycomb Triggers
X-Honeycomb-Webhook-TokenThe value of the Webhook integration’s Shared Secret
You may need to provide additional HTTP headers for the specified webhook endpoint. For example, a webhook endpoint could require a Authentication header with a value of Bearer <your-api-key>. To customize your webhook header(s):
  1. Navigate to Team Settings, and select the Integrations view.
  2. Locate Trigger and SLO Recipients.
  3. Locate the desired Webhook integration in the list of integrations, and select “Edit”.
  4. Select the Headers tab.
  5. Select Add header. You can add up to 5 headers.
  6. Enter a name for the header. The name must:
    1. Be 64 characters or less
    2. Not match Content-Type, User-Agent, or X-Honeycomb-Webhook-Token
  7. Enter a value for the header. The value must be 512 characters or less.

​
Remove a Webhook Integration

To remove a webhook integration, you will need to delete it from your Honeycomb team. Deleting the webhook integration from your team removes it from all associated Triggers and SLOs.
  1. Navigate to Team Settings, and select the Integrations view.
  2. Locate Trigger and SLO Recipients.
  3. Find your webhook integration.
  4. Select Edit.
  5. In the form editor, select Remove.