Skip to main content

Create and manage alerts

Metronome alerts provide for comprehensive monitoring of your customers and billing. Alerts cover a variety of use cases, such as customer spend and usage thresholds, time to plan end, and credit balance drawdowns. You can establish alerts for individual customers, every customer on a specific plan, or across all customers.

Create an alert​

You can create alerts through the Metronome app or the /alerts/create endpoint.

Note that Metronome uses webhook notifications to notify you of alert status changes; you'll need to create a webhook endpoint on your server to handle these events.

This example creates an alert for when a customer's credit balance reaches $10 remaining, with a low credit balance alert and a webhook notification for customers on a specific plan:

creating an alert in the Metronome app

Create alerts on behalf of your customers

Your customers may want the ability to enable their own notifications (for example, when their balance is low). You can build that functionality into your product, and then call the Metronome /alerts/create endpoint accordingly.

Alert types​

Metronome offers five alert types. Each type is measured either once per day or continuously throughout the day. Every alert type goes into an in_alarm state when the threshold is met. (See also the alert triggers for details of the alert evaluation process.)

Low credit balance reached​

This alert type sets a threshold for a specific credit type. The alert labels a customer as in_alarm if the customer's balance for the credit type reaches or goes below your set threshold. This alert type is measured throughout the day.

Customers without credits

If a customer has never been issued credits, they are treated the same as customers with 0 credits left: their alert remains in_alarm until they are issued credits above the threshold.

Spend threshold reached​

This alert type sets a threshold for a specific credit type. The alert labels a customer as in_alarm if the customer's spend for their current billing period reaches or goes above your set threshold. This alert type is measured throughout the day.

Low remaining days in plan​

This alert type sets a threshold for number of days remaining in a customer's current plan. The alert labels a customer as in_alarm if the remaining days left in the customer's plan reaches or goes below your set threshold. This alert type is measured once a day.

When using this alert type, consider this expected behavior:

  • A customer without a plan is considered as having 0 days left.
  • When this alert is scoped to all customers on a specific plan, the alert is only evaluated when that plan is active. When a customer's plan ends, they are no longer covered by the plan-scoped alert. Therefore, you cannot set a threshold less than one day in this scenario (as the plan must be active to evaluate the alert).
  • When this alert is scoped to all customers or to an individual customer without specifying the plan, the alert is evaluated regardless of whether a plan is active or inactive. As a result, when the low remaining days in plan alert is set to 0 and the customer does not have an active plan, the alert goes into alarm on the next run of the daily alert evaluations.

Low remaining credit percentage​

This alert type sets a percentage threshold for a specific credit type. The alert labels a customer as in_alarm if the percentage of available credits on all active credit grants for that credit type reaches or goes below your set threshold. This alert type is measured once a day.

The low remaining credit grant percentage only takes into account active credit grants. The alert calculation automatically excludes expired credits. Low credit balance alerts only apply to the total credit balance on a customer, and cannot be specific to a credit grant.

Usage threshold reached​

This alert type sets a threshold for a specific billable metric. The alert labels a customer as in_alarm if the customer's usage for their current billing period (or previous billing period if events are received during the grace period) reaches or goes above your set threshold. This alert type is measured once a day but only applies to customers on a plan.

Alert states​

As the data relevant to alerts is evaluated, the alert state may be updated. The three alert states are:

  • evaluating

    The state for an alert that has yet to be evaluated, typically due to a customer having just been created. To avoid race conditions, Metronome does not evaluate an alert within the first two minutes of customer creation.

  • ok

    The state for an alert that has been evaluated but the customer is below the alert threshold. For example, a $200 spend threshold alert is considered in OK state for a customer with only $100 of spend.

  • in_alarm

    The state for an alert that has been evaluated and the customer has breached the alert threshold. For example, a $200 spend threshold alert is considered in_alarm as soon as the customer spends $200 or more.

Invoices and alerts

Despite potential lag in the pipelines, usage alerts and invoice generation pull from the same usage aggregation source. Invoices and alerts should always reflect the same customer state.

Access alert information​

You can view all of your alerts and their statuses in the Metronome app. To view a specific customer's alerts, select the customer and then click on the Alerts tab.

Through the API, you can retrieve a customer's alert status and alert information for a specific alert using the/customer-alerts/get endpoint. Retrieve every alert using the /customer-alerts/list endpoint.

Archive an alert​

You can archive an alert through the Metronome app or the API using the /alerts/archive endpoint.

Update an alert

To update an alert--for example, to change the threshold--first archive it (using the Metronome app or API), then create it anew with the updated value.

Alert triggers​

To assess whether or not an alert notification should be sent, Metronome routinely evaluates customers with associated alerts. If a customer's watched value--credit balance, spend, and so on--hits a threshold, an alert notification is sent.

There are three possible triggers for an evaluation:

  • Usage events are ingested

  • Customer metadata changes (for example, a plan is assigned or a new ingest alias is assigned)

    Specifically, any CRUD (create, retrieve, update, and delete) action impacting alerts, customers, customer ingest aliases, plans (Plan table), customer-specific plans (CustomerPlan table), and credit grants are considered metadata changes and trigger an alert evaluation.

  • Time passes

    Alerts triggered by time-based state transitions (for example, a new billing period starts or ends or a credit grant starts or expires) are evaluated at 00:00UTC on the specified date of transition. Daily alert types (such as low remaining days in a plan or low remaining credit percentage and usage threshold) are evaluated at 18:00UTC every day.

Spend threshold and credit threshold alerts have notifications sent within minutes of that condition being met. Daily alerts are evaluated at 18:00UTC and sent out shortly thereafter with a 24-hour SLA.

Webhook notifications​

When a customer's alert status transitions to in_alarm, Metronome sends a webhook notification. See the webhooks documentation for requirements and best practices in setting up your webhook endpoint.

Metronome maintains an internal system for alert notification failures. You may be contacted directly if your webhook fails to acknowledge notifications. However, should you have concerns about alert functionality:

  • Review the alert state via the API
  • If you see that the alert is in_alarmand you do not receive a notification, review the associated webhook endpoint configuration, and test a customer in sandbox to validate the notification process with another alert
  • If you see that the alert is ok but you suspect that it should be in alarm, review the customer profile in the UI for any recent changes (e.g., a new credit grant purchase)

Metronome alerts send notifications as soon as the system transitions them to the in_alarm state. However, there are some instances in which some time may pass between a change of state in Metronome and the notification being sent:

  • Metronome does not evaluate alerts for the first two minutes after customer creation to avoid race conditions
  • In rare cases, lag may be introduced due to a delay in the events pipeline or a spike in activity leading to a large alert evaluation or notification queue

The below shows example webhook payloads for each alert type.

{
  "id": "34c2cd16-b598-42dc-9f6c-62fd0fe37da1",
  "type": "alerts.low_credit_balance_reached",
  "properties": {
    "customer_id": "5f24bd14-2909-4202-8b0d-b1af914d7460",
    "alert_id": "41e5fd1b-7ff1-4731-8e01-b495db46c9be",
        "timestamp": "2023-06-06T00:00:00Z"
  }
}
Metronome logoMetronome logo
© 2023 Metronome. All rights reserved.
CareersBlogLog in