> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeycomb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Alerts to Webhooks

> Route Honeycomb Trigger and SLO burn alerts to any service that accepts a JSON payload, including third-party tools and custom integrations.

The Webhooks + Honeycomb integration uses [Honeycomb Triggers](/notify/triggers/) or [Honeycomb Service Level Objective (SLO) Burn Alerts](/notify/slos/) 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.

If a delivery attempt fails due to a transient error, Honeycomb may automatically retry the request.
Each request includes an `X-Honeycomb-Webhook-Delivery-ID` header with a unique identifier that stays the same across retries of the same delivery, so your endpoint can use it to deduplicate requests.

You can [customize your webhook](#customize-your-webhook) in Honeycomb with [functions](/notify/webhooks/functions/) and [variables](/notify/webhooks/variables/).
View our available [example webhook templates](/notify/webhooks/example-templates/) for inspiration.

Refer to our API documentation for [programmatic management of webhook notifications](/api/recipients/).

## 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](#customize-your-webhook) by using the [Payload](#customize-webhook-payload), [Variables](#customize-webhook-variables), and/or [Headers](#customize-webhook-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](/notify/webhooks/example-templates/) for inspiration.
4. Optionally, you can configure and include custom [variables](#customize-webhook-variables) and [headers](#customize-webhook-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](#configure-triggers-to-use-your-webhook) or [SLO Burn Alert](#configure-slo-burn-alerts-to-use-your-webhook) 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](/notify/webhooks/variables/) includes a list of available variables.

Optionally, these variables can be [overridden](#override-payload-template-variables) 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](#create-a-webhook) 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:

```text theme={}
{{ .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 name                       | Value                                                                                                                                     |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `Content-Type`                    | `application/json`                                                                                                                        |
| `User-Agent`                      | `Honeycomb Triggers`                                                                                                                      |
| `X-Honeycomb-Webhook-Token`       | The value of the Webhook integration's **Shared Secret**                                                                                  |
| `X-Honeycomb-Webhook-Delivery-ID` | A unique identifier for this webhook delivery. Consistent across retries of the same delivery, so you can use it to deduplicate requests. |

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**.