Skip to main content
Usage alerts let you define thresholds on usage metrics, costs, or wallet balances and receive notifications when those thresholds are crossed. They help you stay informed about customer activity without polling the API.

​
Alert Types

Monigo supports three alert types, each monitoring a different dimension of customer activity.

​
Usage Exceeded

Fires when a customer’s metered usage on a specific metric crosses a threshold. Useful for notifying customers approaching their plan limits. 
curl -X POST https://api.monigo.co/api/v1/alerts?org_id=YOUR_ORG_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "usage_exceeded",
    "scope": "plan",
    "scope_id": "PLAN_ID",
    "metric_id": "METRIC_ID",
    "thresholds": [
      { "value": "8000", "label": "80% of limit" },
      { "value": "10000", "label": "100% of limit" }
    ],
    "require_acknowledgment": false
  }'

​
Cost Exceeded

Fires when the estimated cost for a billing period crosses a threshold. Specify the currency field to match the subscription’s billing currency. 
curl -X POST https://api.monigo.co/api/v1/alerts?org_id=YOUR_ORG_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cost_exceeded",
    "scope": "subscription",
    "scope_id": "SUBSCRIPTION_ID",
    "currency": "NGN",
    "thresholds": [
      { "value": "50000", "label": "Budget warning" },
      { "value": "100000", "label": "Budget exceeded" }
    ],
    "require_acknowledgment": true
  }'

​
Wallet Balance Dropped

Fires when a customer’s wallet balance drops below a threshold. Helps you prompt customers to top up before their balance runs out. 
curl -X POST https://api.monigo.co/api/v1/alerts?org_id=YOUR_ORG_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "wallet_balance_dropped",
    "scope": "customer",
    "scope_id": "CUSTOMER_ID",
    "currency": "NGN",
    "thresholds": [
      { "value": "5000", "label": "Low balance" },
      { "value": "1000", "label": "Critical balance" }
    ],
    "require_acknowledgment": false
  }'

​
Plan-Level Alerts

When you set scope to "plan", the alert applies to every subscription on that plan. Monigo automatically creates per-subscription tracking states when the alert is evaluated, so you do not need to create individual alerts for each customer. 
curl -X POST https://api.monigo.co/api/v1/alerts?org_id=YOUR_ORG_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "usage_exceeded",
    "scope": "plan",
    "scope_id": "PLAN_ID",
    "metric_id": "METRIC_ID",
    "thresholds": [
      { "value": "800", "label": "80%" },
      { "value": "1000", "label": "100%" }
    ],
    "require_acknowledgment": false
  }'

​
Multiple Thresholds

Each alert supports multiple thresholds, evaluated in order. When the monitored value crosses the first threshold, Monigo fires a notification and advances to monitoring the next threshold. This lets you set up escalating warnings (for example, 80% and 100%) in a single alert definition. Each threshold has a value (the numeric boundary) and an optional label (a human-readable description included in webhook payloads).

​
Alert Lifecycle

An alert progresses through these states:
  1. Created — The alert is defined with its thresholds and begins monitoring.
  2. Triggered — The monitored value crosses a threshold. Monigo fires a webhook event and records the triggered state.
  3. Acknowledged — If require_acknowledgment is true, a team member or API call acknowledges the alert. This is recorded for audit purposes.
  4. Reset — At the start of each new billing period, triggered states are automatically reset so thresholds can fire again.

​
Webhook Events

When thresholds are crossed or alerts change state, Monigo dispatches webhook events to your configured endpoints.
Event TypeFired When
alert.triggeredA threshold is crossed for the first time in the current billing period.
alert.acknowledgedA triggered alert is acknowledged via the API or dashboard.
alert.resolvedThe monitored value drops back below the threshold.
alert.disabledAn alert is disabled via the API or dashboard.

​
Managing Alerts

​
List Alerts

curl https://api.monigo.co/api/v1/alerts?org_id=YOUR_ORG_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
Filter by type, scope, or customer: 
curl "https://api.monigo.co/api/v1/alerts?org_id=YOUR_ORG_ID&type=usage_exceeded&scope=plan" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Update Thresholds

curl -X PUT https://api.monigo.co/api/v1/alerts/ALERT_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "thresholds": [
      { "value": "9000", "label": "90%" },
      { "value": "10000", "label": "100%" }
    ]
  }'

​
Enable or Disable

# Disable
curl -X POST https://api.monigo.co/api/v1/alerts/ALERT_ID/disable \
  -H "Authorization: Bearer YOUR_API_KEY"

# Enable
curl -X POST https://api.monigo.co/api/v1/alerts/ALERT_ID/enable \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Delete

curl -X DELETE https://api.monigo.co/api/v1/alerts/ALERT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Best Practices

  • Use 80%/100% thresholds. An early warning at 80% gives customers time to adjust before hitting the limit.
  • Enable require_acknowledgment for critical alerts. This ensures someone on your team explicitly reviews cost or usage spikes before they are dismissed.
  • Combine with webhook endpoints. Route alert.triggered events to Slack, PagerDuty, or your internal tooling for real-time visibility.
  • Prefer plan-level alerts over per-subscription alerts. Plan-level alerts automatically cover all subscribers and reduce configuration overhead.
  • Set wallet balance alerts above zero. Alerting at a low-but-nonzero balance gives customers a window to top up before service is interrupted.