Webhooks

Create incidents automatically from external tools using webhooks.

Overview

Runframe webhooks allow you to create incidents from any monitoring tool, custom script, or third-party service. Send a POST request to Runframe with incident details and we’ll create the incident and notify your team.

Webhook endpoint

https://api.runframe.io/webhooks/{routingKey}

Each integration (Datadog, Sentry, Prometheus, Custom) gets a unique routing key that acts as both:

1. Identifier - Routes webhooks to your organization
2. Security token - Authenticates requests (like an API key)

Get your webhook URL from Settings → Integrations in the Runframe dashboard.

Creating a webhook

Generate a webhook URL

1. Navigate to Settings → Integrations
2. Click Connect for your integration (Datadog, Sentry, Prometheus, or Custom)
3. Copy the unique webhook URL (includes your routing key)
4. Link services to route alerts to specific teams

Configure your tool

Use the webhook URL in your monitoring tool or custom script:

curl https://api.runframe.io/webhooks/abc123def456... \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "title": "API latency spike",
    "severity": "High",
    "description": "API response times > 5s",
    "service": "api-backend"
  }'

Webhook payload

Required fields

Optional fields

Example payloads

Minimal incident

{
  "title": "Server is down"
}

Complete incident

{
  "title": "Database connection pool exhaustion",
  "description": "Database connections exhausted. API returning 500 errors.",
  "severity": "High",
  "service": "database",
  "affected_services": ["api-backend", "database"],
  "customer_impact": true
}

Custom fields

Include additional fields as metadata:

{
  "title": "High error rate",
  "severity": "Medium",
  "error_rate": "15%",
  "region": "us-east-1",
  "environment": "production"
}

Custom fields are attached to the incident for reference but don’t affect workflow.

Response format

Success response

{
  "success": true,
  "incident": {
    "id": "INC-042",
    "title": "API latency spike",
    "severity": "High",
    "status": "investigating",
    "url": "https://app.runframe.io/incidents/INC-042"
  }
}

Error response

{
  "success": false,
  "error": {
    "code": "ROUTE_NOT_FOUND",
    "message": "Webhook routing key is invalid or expired"
  }
}

Retry behavior

If the webhook endpoint returns an error or times out:

After 5 failed attempts, the webhook is disabled and you’ll receive a notification.

Security

Keep webhook URLs secret

Treat webhook URLs like passwords. Anyone with the URL can create incidents in your organization.

Best practices:

• Don’t commit webhook URLs to git
• Use environment variables for scripts
• Rotate webhook URLs if they’re accidentally exposed
• Disconnect unused integrations

IP whitelisting (optional)

Restrict webhook requests to specific IP ranges:

1. Navigate to Settings → Integrations
2. Edit your integration
3. Add allowed IP ranges in CIDR notation (e.g., 192.168.1.0/24)
4. Save changes

Requests from IPs outside the whitelist will be rejected.

Testing webhooks

Test from the dashboard

1. Navigate to Settings → Integrations
2. Click Test next to your integration
3. Runframe sends a test incident
4. Verify the incident was created correctly

Test with curl

curl https://api.runframe.io/webhooks/abc123def456... \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Test webhook",
    "description": "Testing webhook integration"
  }'

Monitoring webhook health

View webhook delivery status in Settings → Integrations:

Examples

Datadog webhook

curl https://api.runframe.io/webhooks/abc123def456... \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "title": "{{alert.name}}",
    "description": "{{alert.text}}",
    "severity": "{{alert.priority}}"
  }'

Sentry webhook

curl https://api.runframe.io/webhooks/abc123def456... \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "title": "{{event.title}}",
    "description": "{{event.culprit}}",
    "severity": "{{event.level}}"
  }'

Prometheus Alertmanager webhook

receivers:
  - name: 'runframe'
    webhook_configs:
      - url: 'https://api.runframe.io/webhooks/abc123def456...'
        send_resolved: true

Custom monitoring script

import requests
import os
 
webhook_url = os.environ['RUNFRAME_WEBHOOK_URL']
 
def create_incident(title, severity, description):
    payload = {
        'title': title,
        'severity': severity,
        'description': description
    }
    response = requests.post(webhook_url, json=payload)
    return response.json()
 
# Usage
incident = create_incident(
    title='High memory usage',
    severity='Medium',
    description='Memory usage above 90% on production servers'
)

Need more?

• Authentication – Webhook security and IP whitelisting
• Integrations – Pre-built Datadog, Sentry, and Prometheus guides
• Slash Commands – Complete /inc command reference
• Web Dashboard – Webhook management UI