Configure Alerts
Configure alert policies and contact points in API7 Gateway to get notified by email or webhook when gateway instances go offline, certificates expire, or error rates breach a threshold.
API7 Gateway monitors gateway instances, certificates, license usage, and request status codes, and can notify you when these conditions cross a threshold. Alerting is built around three concepts you configure in API7 Dashboard:
- Contact Points — reusable destinations for notifications (Email or Webhook).
- Alert Policies — the conditions to evaluate (event, rule, gateway groups, check interval) and which contact points to notify when triggered.
- Alert History — a 30-day log of past alerts and the notifications that were delivered.
For background on how alerts are evaluated and delivered, see Alerts and SLOs.
Configure a contact point
Before you create a policy, configure at least one contact point so the gateway has somewhere to send notifications.
- From the top navigation bar, select Organization, then Contact Points.
- Click Add Contact Point and choose either:
- Email — enter one or more recipient addresses. Email delivery requires an SMTP server, which you configure under Organization > Settings > SMTP Server.
- Webhook — enter the destination URL. Use this to forward notifications to Slack (via Slack Incoming Webhooks), PagerDuty, Microsoft Teams, or any HTTP endpoint that accepts an alert payload.
You can attach multiple contact points to a single alert policy, so a policy can notify both an on-call email list and a Slack channel.
Recommended alert policies
The Dashboard exposes more than 20 built-in event types. The following policies are recommended for most production deployments. Each is created from Alert > Policies > Add Alert Policy.
| Event | Why it matters | Suggested check interval |
|---|---|---|
| Gateway instance offline | A data plane node has stopped reporting heartbeats and is no longer serving traffic. | 60 minutes |
| mTLS certificate between control plane and data plane will expire | Validity is chosen per data plane at install time — 1, 2, 3, 5 or 10 years, defaulting to 10 — and rotation is manual, so the alert is how you find out. Expiry breaks CP–DP communication. | 1440 minutes (daily) |
| SSL certificate will expire | Listener TLS certificates need to be rotated before clients see TLS errors. | 1440 minutes (daily) |
| Allowed License CPU Quota Exceeded | The combined CPU cores of all data plane instances has exceeded the quota allowed by your API7 Enterprise license. | 60 minutes |
| Number of healthy gateway instances | Detect when a gateway group falls below the minimum instance count required for your SLO. | 30 minutes |
| Number of status code 500 / Ratio of status code 500 | Surface upstream or gateway failures that affect a measurable share of traffic. | 30 minutes |
For how the control plane evaluates these policies, see How policies are evaluated. For the variables you can use in notification templates, see Alert Variables and Templates.
How policies are evaluated
The control plane runs a background job that evaluates every alert policy once a minute against its conditions and thresholds, and notifies the policy's contact points when they are met. Consequences worth planning around:
- The Admin API accepts a check interval as low as one second (
check_intervalis validated in seconds, minimum1). While a condition holds, the policy notifies its contact points at every interval — set the interval to how often you want to be told, not to how often you want the condition checked. A very short interval means very frequent notifications while the condition holds; pick a value your contact points can absorb, not just the shortest one the API allows. - A policy triggers in either
ALLorANYmode, and the two cannot be combined in one policy.ALLfires when every condition is met;ANYfires when any one is. Express a condition that needs both shapes as two policies. - Severity (High, Medium, Low) is informational. It is included in the notification so your receiving system can route on it, but it does not change how or when API7 evaluates or delivers the alert.
- A contact point is an organization-level object, not a property of a policy. Point many policies at one contact point and a changed webhook URL or email address is a single edit. Email contact points need the SMTP server configured under Organization > Settings, and the control plane must be able to reach the destination.
Alert logs record the configuration that fired and the request and response of each delivery attempt, which is what you need when an alert was raised but never arrived.
Customize notification content
Email subjects, email bodies, and webhook payloads can include the following template variables:
| Variable | Description |
|---|---|
{{ .AlertPolicyName }} | Name of the alert policy. |
{{ .Description }} | Description of the alert policy. |
{{ .Severity }} | Severity (High, Medium, or Low). |
{{ .TriggerGatewayGroup }} | Comma-separated names of the gateway groups that triggered the alert. |
{{ .AlertTime }} | Time of the alert. Format with {{ .AlertTime.Format "2006 Jan 02 15:04:05" }}. |
{{ .AlertDetail }} | Human-readable description of the events that triggered the alert. Use the escape function ({{ .AlertDetail | escape }}) when embedding in a JSON webhook body. |
For the complete reference, see Alert Variables and Templates.
Review alert history
Alert events and the notifications delivered for them are retained for 30 days. To inspect them, select Alert from the side navigation bar, then click History. Each record includes the policy that fired, severity, trigger time, gateway groups involved, and the alert detail that was sent.
Next steps
- Monitor Metrics — refine alert thresholds against the metrics they evaluate.
- Configure Distributed Tracing — investigate the root cause of a fired alert.
- Configure Centralized Logging — correlate alert events with the corresponding access and error log entries.