# Incoming webhooks

Create incidents automatically from any tool that can send a payload, even from your custom scripts. The **incoming webhook** integration allows you to parse custom data, set creation rules, and map fields to create detailed, actionable incidents.

## Getting started

1.  Go to **Integrations** → [Importing data](https://uptime.betterstack.com/team/0/integrations/importing-data ";_blank").
2.  Find the **Incoming webhook** card and click **Add**.
3.  Give your integration a **Name** and click **Save changes**.
4.  Copy the unique **Webhook URL**. This is the endpoint your external service will send `POST` requests to.

[info]
To test your configuration, you can paste a sample JSON payload into the **Sample webhook data** field. This lets you preview how Better Stack will parse the data and apply your rules without sending real requests.
[/info]

## Configuring the webhook

Once you have your webhook set up, you can configure how it processes incoming data to create, update, and resolve incidents.

### Incident creation rules

Define when an incident should be created. You can set up one or more conditions based on the **keys** and **values** in your JSON payload. If **ANY** or **ALL** of the conditions match—depending on your configuration—an incident will be created.

For example, you can create an incident when the `incident.status` field in the payload contains the word `alert`.

### Data extraction

Map data from your webhook's JSON payload directly to Better Stack incident fields. This enriches your incidents with contextual information, making it easier to understand and debug issues.

You can extract data for the following fields:

*   **Title**: The main title of the incident.
*   **Cause**: A short description of what triggered the incident.
*   **Alert ID**: A unique identifier for the incdient, which can avoid duplicates.
*   **Metadata**: Any [metadata](https://betterstack.com/docs/uptime/incident-metadata/) can be extracted from the webhook payload.

Extract values by specifying the **JSON key**, **HTTP header**, or parse the **request body** in full. Further match the contents by matching text **before**, **after**, or **between** specific texts, or using **regular expressions**.

### Acknowledging and resolving incidents

Configure rules to automatically acknowledge or resolve incidents based on the incoming payload.

*   **Acknowledging incidents**: Set conditions to automatically acknowledge an incident. By default, this is set to **Never**, requiring manual acknowledgment.
*   **Resolving incidents**: Set conditions to automatically resolve an incident. For example, you can auto-resolve if the `incident.status` field contains the word `resolved`. By default, this is set to **Never**, requiring manual resolution.

### On-call escalation

Define who gets notified when an incident is created. You can use a **simple escalation**, use one of your existing [escalation policies](https://betterstack.com/docs/uptime/escalation-policies/), or create a new one with specific steps, notification channels, and time-based rules.

### Advanced settings

*   **Recovery period**: Set a [recovery period](https://betterstack.com/docs/uptime/confirmation-and-recovery-period/) to define how long an alert must remain stable before being automatically marked as resolved. The default is **Immediate recovery**.
*   **Metadata**: Attach custom key-value pairs (for example, `datacenter: us-west-1`) to incidents. This metadata can be used for advanced filtering or routing rules in your escalation policies.

## Example configuration

Let's walk through an example of how to configure a webhook for a monitoring tool.

```json
[label Sample webhook payload]
{
  "incident": {
    "id": "alert-12345",
    "status": "high severity alert",
    "severity": "high",
    "title": "Database connection errors",
    "description": "The primary database is experiencing intermittent connection failures.",
    "metadata": {
      "datacenter": "us-west-1",
      "service": "payments-api"
    }
  }
}
```

Based on this payload, here’s how you could configure your webhook:

**1. Incident creation rule**

*   Create an incident when `incident.status` contains `alert`.
*   Result: This condition matches, so an incident will be created.

**2. Data extraction**

*   **Title**: Extract from `incident.title`  
    "Database connection errors"
*   **Cause**: Extract from `incident.description`  
    "The primary database is experiencing intermittent connection failures."
*   **Alert ID**: Extract from `incident.id` by extracting text after `-`  
    "12345"
*   **Metadata**: You can extract multiple [metadata fields](https://betterstack.com/docs/uptime/incident-metadata/):
    *   **Datacenter**: Extract from `incident.metadata.datacenter`  
        "us-west-1"
    *   **Service**: Extract from `incident.metadata.service`  
        "payments-api"
    *   **Scope**: Extract from  `incident.metadata.service`, match text before `-`  
        "payments"
    *   **Severity**: Extract from `incident.severity`  
        "high"

**3. Incident resolution rule**

*   Automatically resolve if `incident.status` contains `resolved`.
*   **Alert ID**: Same setting as when creating incidents

With this setting, the following would automatically resolve the incident:

```json
[label Example webhook payload that would auto-resolve the incident]
{
  "incident": {
    "id": "alert-12345",
    "status": "resolved",
    "severity": "high",
    "title": "Database connection errors",
    "description": "The primary database is experiencing intermittent connection failures."
  }
}
```

[success]
#### That's all. 🎉
Your webhook is now configured. Incidents will be automatically created and resolved based on the data you send to your unique webhook URL.
[/success]

## Need help?

Please let us know at [hello@betterstack.com](mailto:hello@betterstack.com). We're happy to help. 🙏