Custom Webhook

Create Runframe incidents from any HTTP source. Payload format, deduplication, and examples.

Setup

Navigate to Integrations Hub
Click Connect Custom Webhook
Copy the unique webhook URL (format: https://runframe.io/webhooks/{routingKey})
Configure your tool to POST JSON to this URL

Payload format

Required fields

Field	Type	Description
`title`	string	Brief incident summary (max 200 chars)
`service_id`	string	Service ID to route the incident to (e.g., `SER-00001`)

Optional fields

Field	Type	Description
`description`	string	Detailed description (max 2000 chars)
`severity`	string	`SEV0`, `SEV1`, `SEV2`, `SEV3`, or `SEV4` (default: uses fallback chain)
`status`	string	`new`, `investigating`, or `resolved` (default: `new`)
`source_url`	string	Link back to the source (dashboard, CI run, etc.)
`dedup_key`	string	Deduplication key, same key = same incident (max 255 chars)
`metadata`	object	Key-value pairs for additional context (max 10 keys)

Examples

Minimal

{
  "title": "Server is down",
  "service_id": "SER-00001"
}

Complete

{
  "title": "Database connection pool exhaustion",
  "service_id": "SER-00002",
  "description": "Database connections exhausted. API returning 500 errors.",
  "severity": "SEV1",
  "status": "new",
  "source_url": "https://grafana.example.com/dashboard/db",
  "dedup_key": "db-pool-prod-001",
  "metadata": {
    "environment": "production",
    "region": "us-east-1"
  }
}

curl

curl -X POST https://runframe.io/webhooks/YOUR_ROUTING_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "title": "High memory usage on production servers",
    "service_id": "SER-00001",
    "description": "Memory usage above 90% on 3 servers",
    "severity": "SEV1"
  }'

Deduplication

If dedup_key is provided, subsequent POSTs with the same key update the existing incident instead of creating a new one
If dedup_key is omitted, every POST creates a new incident

Testing

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

Verify the incident appears in Runframe with the correct title, service, and severity.

On this page