Incident Webhook API

Overview

Automatically create incidents from your monitoring tools like Datadog, PagerDuty, or Prometheus. The Incident API enables your alerting systems to create and track incidents without manual intervention.

Authentication

Create an API token from your account settings to authenticate API requests.

Getting Your API Token

1. Navigate to Admin Settings
2. Click API Tokens
3. Click Create New Token
4. Give your token a name (e.g., "Datadog Integration")
5. Copy the token immediately - you won't see it again!

Create Incidents

Use the API to automatically create incidents from your monitoring alerts.

Basic Example

POST /api/v1/incidents
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "team_id": 5,
  "title": "High CPU usage on web-01",
  "severity": 2,
  "description": "CPU usage exceeded 90% for 5 minutes"
}

API Contract

Request Fields

Field	Type	Required	Description
team_id	integer	✓ Yes	The team ID to create the incident for
title	string	✓ Yes	Brief description of the incident (max 255 characters)
severity	integer	✓ Yes	Must be one of: 1, 2, 3, 4 (1 = critical, 4 = low)
description	text	No	Detailed description of the incident
source	string	No	Source system name (e.g., "datadog", "pagerduty", "prometheus")
external_id	string	No	External system's alert/incident ID (used for idempotency)
metadata	json	No	Arbitrary key-value data from the alert system
tags	array	No	Array of tags for categorization (e.g., ["production", "api"])
assign_to_oncall	boolean	No	Auto-assign to current on-call user
oncall_schedule_id	integer	No	Which on-call schedule to use (required if assign_to_oncall is true)
status	string	No	Initial status (default: "open")

Response (201 Created)

{
  "success": true,
  "data": {
    "id": 1234,
    "title": "High CPU usage on web-01",
    "severity": "Sev 2",
    "status": "open",
    "assigned_to": {
      "id": 42,
      "name": "John Doe",
      "email": "[email protected]"
    },
    "created_at": "2026-01-28T12:34:56Z",
    "url": "https://sizemotion.com/incidents/1234"
  }
}

Error Responses

401 Unauthorized - Invalid or missing API token

{
  "success": false,
  "message": "Unauthenticated"
}

422 Validation Error - Invalid or missing required fields

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "title": ["The title field is required."],
    "severity": ["The severity must be one of: 1, 2, 3, 4."]
  }
}

429 Rate Limit Exceeded - Too many requests

{
  "success": false,
  "message": "Too many requests. Rate limit exceeded."
}

Common Use Cases

Auto-Assign to On-Call

Automatically assign the incident to whoever is on-call:

{
  "team_id": 5,
  "title": "Database connection timeout",
  "severity": "Sev 1",
  "assign_to_oncall": true,
  "oncall_schedule_id": 10
}

Prevent Duplicates

Use your alert system's ID to prevent creating duplicate incidents:

{
  "team_id": 5,
  "title": "High CPU usage",
  "severity": "Sev 2",
  "external_id": "datadog_alert_12345"
}

If an incident with this external_id already exists, the API returns the existing incident instead of creating a new one.

Include Alert Metadata

Store additional context from your monitoring system:

{
  "team_id": 5,
  "title": "High memory usage",
  "severity": "Sev 3",
  "source": "datadog",
  "metadata": {
    "host": "web-01.example.com",
    "metric": "memory.usage",
    "value": 92.5,
    "threshold": 85,
    "alert_url": "https://app.datadoghq.com/alerts/12345"
  },
  "tags": ["production", "web-server", "memory"]
}

Integration Examples

Simple cURL Test

curl -X POST https://your-app.com/api/v1/incidents \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": 1,
    "title": "Test incident from API",
    "severity": "Sev 3"
  }'

Datadog Webhook

Configure Datadog to send alerts to your webhook endpoint. Map Datadog's priority levels to severity:

• P1 → 1
• P2 → 2
• P3 → 3
• P4 → 4

PagerDuty Integration

Set up a webhook in PagerDuty to forward incidents. Use PagerDuty's urgency field to determine severity:

• high urgency → 1 or 2
• low urgency → 3 or 4

Prometheus Alertmanager

Configure Alertmanager to send alerts via webhook receiver. Use alert labels to set severity and team.

Tips & Best Practices

Auto-Assignment

Enable assign_to_oncall to automatically route critical incidents to the engineer on-call. This ensures someone is immediately notified without manual assignment.

Prevent Duplicates

Always include external_id from your monitoring tool. This prevents creating multiple incidents when your alerting system sends the same notification repeatedly.

Rate Limits

Each API token can make up to 60 requests per minute. If you need higher limits, contact your administrator.

Organizing Integrations

Create separate API tokens for each monitoring tool (e.g., "Datadog Production", "Pingdom Staging"). This makes it easier to track which system is creating incidents and to rotate credentials.