Skip to main content

Notifications & Alerting

Real-time alerts & workflows.

The Notifications page has two tabs: Alerts — the live feed of everything that has fired — and Subscriptions — the definitions that control when alerts fire and where they go.

Notifications are workspace-level. Every team member sees the same alert feed and subscription list. Changes take effect immediately — saving or deleting a subscription pushes the updated definitions to all connected SDK instances in real time.

Alerts tab​

The Alerts tab is your operational dashboard for everything that has fired. Alerts are created automatically whenever a subscription's conditions are met.

Alert statuses​

Every alert starts as New. Opening an alert automatically marks it Seen. Click Resolve to mark it done. Use the filter bar to view New, Seen, Resolved, or All alerts.

The filter defaults to New — the unread queue. Use this as your daily triage view.

Alert detail​

Click any alert row to open its detail panel.

Real-time alerts show the credit name and description, entitlement name and plan, previous and current meter values, limit, remaining and overage where applicable, the attempted value for hard limit hits, a visual progress bar showing % of limit consumed, and the associated customer.

Group invoice alerts show the invoice period, total amount and currency, margin for the period, and the customer the invoice is for.

All alerts include a collapsible Raw Event Data section with the complete JSON payload — useful when triaging unusual events or building integrations.

Alert lifecycle​

Alerts persist until resolved — there's no automatic expiry. Resolved alerts remain visible under the Resolved filter for audit history.

Subscriptions tab​

Subscriptions define when alerts fire and what happens. Navigate to the Subscriptions tab and click + New Subscription to create one.

Name and description​

Name — Required. Shown in the alert feed and in email notifications. Use something that makes the trigger obvious: "Growth Customer Overage", "Invoice Created — Enterprise", "Hard Limit Hit".

Description — Optional. Shown in email notifications sent to your team. Use this to add context that helps the recipient act on the alert without opening the dashboard.

Local Event Name​

Optional. A developer-facing identifier for this notification. When set, developers can subscribe to this notification by name in the SDK:

policy.addHandler('my-handler', (key, value) => {
  if (key === 'usage_limit_warning') {
    // fires when this Cloud notification matches
    const event = JSON.parse(value as string);
    yourApp.handleLimitWarning(event);
  }
});

Must be unique across all subscriptions in your workspace. No spaces, cannot start with a number. This is the bridge between Cloud-managed alerting and your in-process SDK handlers — the same event fires both the email action and your addHandler() callback.

Enabled toggle​

Disabled subscriptions don't fire and don't create alerts. Use this to pause a subscription during an incident or while testing without deleting it.

Trigger types​

Group Invoice Created​

Fires when a group invoice closes at the end of a billing period. Use this for notifying your finance team, triggering billing workflows, or alerting on high-value invoices. This trigger has no event type or segment filter — it fires for all customers when their invoice period closes.

Real-Time Event​

Fires immediately when a meter event occurs, evaluated in-process against your running policy. Use this for limit hits, overage alerts, approaching-limit warnings, or any condition that needs a real-time response.

Event TypeWhen it fires
Meter OverageA soft limit has been exceeded and overage is being incurred
Meter ResetA meter has reset at the end of its reset window
Meter ChangedAny successful enforcement call that updates a meter
Hard Limit HitA hard limit has blocked a request

Leave the event type blank to match all four.

Scoping real-time notifications​

Real-time notifications have three independent layers of filtering. All three must pass for a notification to fire.

1. Event type filter​

The coarsest filter. Select which event type this subscription listens to, or leave blank to catch all.

2. Customer segment​

Optional. Select a saved segment to scope the notification to a subset of customers. The segment condition is evaluated against the customer who triggered the event.

Example: alert on overage, but only for Growth and Enterprise customers. Create a segment for customer.plan == "growth" || customer.plan == "enterprise" and attach it to the notification. Free-tier customers triggering overage will be silently ignored. See Managing Customer Segments for how to define segments.

3. Event Condition (Stof)​

Optional. An additional Stof expression that filters by event-specific data. Expand the Event Condition section to add one — the editor validates syntax in real time.

Four variables are available:

event — The full meter event payload: event.meter.value, event.meter.limit, event.meter.old, event.overage, event.remaining, event.entitlement, event.plan.

customer — The customer object: customer.id, customer.plan, customer.type, customer.metadata.

policy — The live Limitr policy API. Call ?policy.value(customer.id, name), ?policy.limit(customer.id, name), and other SDK methods.

data — Shorthand for customer.metadata.

The last expression is the return value — truthy means the notification fires.

Only fire when a specific entitlement first crosses 90%:

event.entitlement == "chat_input" &&
event.meter.old < (event.meter.limit * 0.9) &&
event.meter.value >= (event.meter.limit * 0.9)

Only fire for overages above a minimum amount:

event.overage != null && event.overage > 10000

Fire when storage first crosses 1 GiB:

event.meter.old < 1073741824 && event.meter.value >= 1073741824

Only fire during business hours (UTC):

const hour = Time.now().hour();
hour >= 9 && hour < 17

Email action​

Toggle Email Action on to send an email when this notification fires.

Product Members — Sends to all members of your workspace. The default for operational alerts where the whole team should be aware.

Custom Addresses — Sends to a specific list of email addresses. Press Enter or comma to add each address. Accepts any email address including PagerDuty routing addresses, team aliases, and on-call hooks.

The description field appears in the email body. Use it to give recipients enough context to act without opening the dashboard.

Common subscription patterns​

Overage alert for high-value customers​

  • Trigger: Real-Time Event → Meter Overage
  • Segment: Growth and Enterprise customers
  • Email: Product Members

Hard limit hit — handled in SDK​

  • Trigger: Real-Time Event → Hard Limit Hit
  • Segment: (all customers)
  • Local Event Name: hard_limit_hit
  • Email: (none)

Approaching limit warning (80%)​

  • Trigger: Real-Time Event → Meter Changed
  • Event Condition:
event.meter.value >= (event.meter.limit * 0.8) &&
event.meter.old < (event.meter.limit * 0.8)
  • Email: Product Members

Invoice created notification​

  • Trigger: Group Invoice Created
  • Email: Custom Addresses → finance@yourcompany.com
  • Description: A new billing period has closed. Review the invoice in the Limitr dashboard.

Meter reset alert for Enterprise customers​

  • Trigger: Real-Time Event → Meter Reset
  • Segment: Enterprise customers
  • Local Event Name: enterprise_meter_reset
  • Email: (none — handled in SDK)
Last updated on