Create manual incidents

Most incidents are auto-created by monitors. Sometimes they aren’t, and you want one anyway. This page covers the patterns where manual creation is the right move, and the cleanest way to do it.

Manual incidents page exactly like automatic ones

Set service_id on the create request and the incident runs the service’s escalation policy: same levels, same timeouts, same repeat cycles, same one-click acknowledgement. See making it page someone.

When to create one manually

• A third-party dependency broke something user-visible. Stripe is degraded, AWS is throttling, your CDN is intermittently 502-ing. Your monitors might be showing a partial signal, but you have first-hand evidence.
• A bug surfaced in production that no monitor catches. UI broken for a specific browser, auth flow broken only for SSO users.
• Coordinating a multi-team outage. One canonical incident beats five Slack threads.
• Pre-announced maintenance went sideways. A deploy you’d protected with a maintenance window actually broke something. The maintenance window suppressed the auto-incident, so create one manually.

When not to

• Don’t manually create an incident for an outage a monitor will catch in 60 seconds anyway. The auto-incident will be cleaner, since it has fewer race conditions with responder_status and affected_http_job_ids.
• Don’t create an incident as a stand-in for a Slack message. If you don’t intend to publish it on a status page or trigger paging, just message the team directly.

Two flavors of manual incident

Standalone incident (no status page)

Use this for internal-only tracking. Useful if you want the timeline + paging behavior without publishing.

curl -X POST https://api.siteqwality.com/incident \
  -H "Authorization: Bearer $SITEQWALITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Stripe webhooks intermittently failing",
    "severity": "major",
    "message": "Seeing ~5% failure rate on inbound Stripe webhooks. Investigating."
  }'

Status-page incident (published)

Use this when the outage affects customers and they should know.

curl -X POST https://api.siteqwality.com/status_page/$STATUS_PAGE_ID/incident \
  -H "Authorization: Bearer $SITEQWALITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status_page_id": "<status-page-id>",
    "title": "Some webhook deliveries delayed",
    "severity": "minor",
    "message": "We are seeing increased latency on outbound webhooks. Investigating with our delivery provider.",
    "affected_http_job_ids": []
  }'

The incident appears immediately on the public page.

Linking to affected monitors

Even on manual incidents, set affected_http_job_ids if monitors do exist for the broken thing. This makes the incident appear as a banner on the matching status-page components, and groups it correctly in dashboards.

{
  "affected_http_job_ids": [
    "a3c1f5e0-1234-4abc-9def-aaaaaaaaaaaa",
    "b7d2e601-5678-4def-9abc-bbbbbbbbbbbb"
  ]
}

Making it page someone

A manual incident only pages when it has a service_id, and that service has an escalation policy attached. Add it at creation:

curl -X POST https://api.siteqwality.com/incident \
  -H "Authorization: Bearer $SITEQWALITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Stripe webhooks intermittently failing",
    "severity": "major",
    "message": "Seeing ~5% failure rate on inbound Stripe webhooks. Investigating.",
    "service_id": "<service-id>"
  }'

From there it behaves exactly like a monitor-opened incident: level 1 of the service’s policy fires immediately, the timeout is scheduled, and acknowledging (from the dashboard, a one-click link, or a Slack button) cancels the escalation.

The service’s broadcast targets, if it has any, are also notified.

Silent no-paging is the common mistake

Three situations produce an incident that quietly pages nobody, and none of them return an error:

• No service_id. The incident is created and nothing else happens.
• The service has no escalation policy. Broadcast targets still fire, but nobody is paged.
• The service_id belongs to a different account. It is accepted at write time and then never resolves.

If a manual incident did not page, check the service first.

Severity guidance for manual incidents

Use case	Severity
Documentation site down	minor
Login broken for a subset of users	major
Full outage, billing affected, security event	critical

Severity drives display order, color, and filters. It also picks the urgency used when paging: critical and major page at high urgency, minor at low. Each targeted responder’s own notification rules for that urgency decide which of their contact methods fire, so a minor incident can legitimately reach a different set of devices than a critical one.

Following up

After resolving, especially for major and critical incidents:

• Run a postmortem outside SiteQwality.
• Link the postmortem doc in a final incident update so it’s preserved on the timeline.

Tip

The full update history is preserved on the incident object. GET /incident/{id} returns it sorted chronologically. Useful when generating retro / postmortem docs.

See also

Incidents overview Status vs responder_status, severities, lifecycle.

Status pages Where published incidents appear.