Alerts and Webhooks
An alert is a notification that fires when a monitor produces a result matching a trigger condition. Alerts connect APIContext to your incident-response toolchain so your team learns about problems without watching a dashboard.
Trigger conditions
Each alert listens for one or more result categories:
| Trigger | When it fires |
|---|---|
| Pass | The monitor met all conditions (useful for negative testing: alert when a call that should fail unexpectedly succeeds) |
| Slow | The response completed but exceeded a latency threshold |
| Warning | The response triggered a warning condition (by default, 4xx HTTP status) |
| Error | The response triggered an error condition (by default, 5xx HTTP status) |
| SLA | The call or workflow step exceeded its Service Level Objective for duration or another SLA metric |
You can also set a failure threshold on an alert, so that it fires only after several failures in a row. How an alert decides to fire explains how the count works.
How an alert decides to fire
Every scheduled run of a monitor produces a result, and each result has a category: Pass, Slow, Warning, Error, or SLA. An alert whose trigger matches that category fires, unless its failure threshold holds it back. Two settings decide how many results a problem produces before anyone hears about it: the failure threshold on the alert, and retries on the monitor.
Failures in a row
The failure threshold is the alert's Only alert after this many failures in a row field (for email alerts, Send email after this many failures in a row). Leave it at 0 or 1 to alert on every matching result. When it is 2 or more, APIContext counts the streak like this:
- Per monitor, across all locations. The count follows the monitor, not the node. Results from every location the schedule uses go into the same streak, in the order they ran.
- Same category only. The streak is the number of consecutive results with the same category as the latest one. A Pass ends the streak, and so does a result of a different category: an Error after three Warnings starts a new count at 1.
- Every day starts again. Only results since midnight UTC count, so a problem that carries on overnight starts a new streak after midnight.
- Repeats at each multiple. With a threshold of N, the alert fires at the Nth result in a row, then again at 2N, 3N, and so on, for as long as the streak lasts.
A Pass alert is never held back by the threshold.
Worked example
A monitor runs every 5 minutes on a worldwide schedule, so each run comes from a different node. Its Error alert has a threshold of 3.
| Time | Node | Result | Streak | Alert |
|---|---|---|---|---|
| 10:00 | London | Error | 1 | No |
| 10:05 | Virginia | Error | 2 | No |
| 10:10 | Tokyo | Error | 3 | Yes |
| 10:15 | Frankfurt | Error | 4 | No |
| 10:20 | Sydney | Error | 5 | No |
| 10:25 | London | Error | 6 | Yes (2 x 3) |
| 10:30 | Virginia | Pass | 0 | No (the streak ends) |
| 10:35 | Tokyo | Warning | 1 | No (a new streak, of Warnings) |
Because the count is per monitor, a single node that fails while the others pass never builds a streak: each Pass resets it. A threshold suits failures that affect every location. To hear about one bad location, use a threshold of 1, or a schedule that runs from that location only.
Retries before a result is recorded
By default, a failed run is recorded as a failure the first time, except when a request fails at the network level, in which case the node first checks its own internet connection to ensure connectivity before reporting a failure.
Retry on failure
Retry on failure is an opt-in setting that runs a failed monitor again before the next scheduled run. Set it on a schedule (in the schedule's settings), on a workflow (its Advanced tab), or on a single monitor (its Advanced tab). A setting on a monitor overrides the workflow's and the schedule's, and a setting on a workflow overrides the schedule's. Never retry on a monitor turns retries off for that monitor even when its schedule retries.
There are three methods. Each sets the wait between one retry and the next:
| Method | Wait between retries |
|---|---|
| Fibonacci retry | 1, 1, 2, 3, 5, 8 seconds, and so on, so retries start 1, 2, 4, 7, 12, 20 seconds after the failed run |
| Exponential retry | factor x baseretry seconds; with a base of 2 and a factor of 1, retries start 1, 3, 7, 15 seconds after the failed run |
| Constant retry | The same interval each time (for example 10, 20, 30 seconds after the failed run) |
A result is retried when it is a Warning or an Error, other than an SLA warning or error: a run that was slow still worked, so it is not retried. Retries go on until a retry passes, until the waits add up to more than the schedule's interval (so the last retry starts before the next scheduled run), or until Maximum retries is reached, if you set it.
Each retry produces its own result. Two options decide how retries affect the rest of the product:
- Skip notifications for retries: the number of retries before a retry result can trigger alerts and webhooks. Without it, a failed retry alerts like any other result.
- Ignore failures in statistics: the number of retries before a failed retry counts in the monitor's statistics.
Retries and the failure threshold work together. A threshold waits for the problem to persist across scheduled runs; a retry checks again within seconds. For an API that fails briefly and recovers, Retry on failure with Skip notifications for retries keeps the alert quiet when the retry passes.
Delivery channels
APIContext delivers alerts to a wide range of platforms:
- Email: simple but not recommended for high-volume scenarios
- Webhooks: Slack, Microsoft Teams, PagerDuty, OpsGenie, VictorOps, BigPanda, Datadog, New Relic, StatusPage, and others
- OpenTelemetry: the recommended default; sends structured telemetry to any OTLP-compatible backend (Axiom, Hydrolix, Honeycomb, etc.)
Each integration type has its own configuration fields (e.g., PagerDuty requires an integration key and severity level).
Scope: per-monitor vs. global
Alerts can be configured on a single monitor or globally for every monitor in a project. Global alerts save setup time when you want the same notification rules across all endpoints.
Organization-wide alert suppression is also available from Organization settings, which disables all alerts until re-enabled.
See also
- Setting up alerts and webhooks: step-by-step configuration guide
- Conditions and assertions: the rules that determine pass, warning, and error outcomes
- Alerting capabilities: platform overview of escalation paths and team routing