Concepts
What is a Custom Incident?
Understand how Custom Incidents let you trigger the escalation machinery manually for things that can't be probed automatically.
A Custom Incident is a manually-controlled incident source — essentially a check with no URL and no worker. You create it, give it a title, attach an escalation policy, and flip its status (UP / DOWN) via API.
How it Differs from an Auto-Triggered Incident
| Auto Incident | Custom Incident | |
|---|---|---|
| Source | Worker probe failure | Manual API call |
| Has URL / endpoint | Yes | No |
| Has interval / confirm period | Yes | No |
| Triggers escalation | Automatically | When you set status to DOWN |
| Resolves automatically | Yes — when probes pass the recover period | No — only when you set status back to UP |
When to Use Custom Incidents
Custom Incidents are for situations that can't be detected by a probe:
- A third-party dependency goes down and you want to notify your on-call team
- A planned degradation needs to be communicated through the same escalation channels
- An issue is detected by an external system (a human, a script, another monitoring tool) and you want to route it through MonitoringDog's escalation and on-call machinery
How it Works
- Create a Custom Incident via the API with status
UP. - When an issue occurs, set the status to
DOWNviaPATCH /v1/custom-incidents/:id. - MonitoringDog opens an incident and the attached escalation policy fires — same as any check-based incident.
- When the issue is resolved, set the status back to
UPto close the incident and send resolution alerts.