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 in your Uptime dashboard.
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.

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 can be extracted from the webhook payload.

Rxtract 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, or create a new one with specific steps, notification channels, and time-based rules.

Advanced Settings

• Recovery period: Set a 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.

{
  "incident": {
    "id": "alert-<12345-starting>",
    "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: Parse from incident.id by extracting text between < and -
  "12345"
• Metadata: You can extract multiple metadata fields:
  • 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:

{
  "incident": {
    "id": "alert-<12345-resolving>",
    "status": "resolved",
    "severity": "high",
    "title": "Database connection errors",
    "description": "The primary database is experiencing intermittent connection failures."
  }
}

Need help?

Please let us know at hello@betterstack.com. We're happy to help! 🙏