Metronome alerts provide for comprehensive monitoring of your customers and billing. Alerts cover a variety of use cases for managing product access, such as gating customer spend, setting usage thresholds, and monitoring commitment drawdowns. You can establish alerts for individual customers 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 must create a webhook endpoint on your server to handle these events. This example creates an alert for when a customer’s credit balance reaches $5 remaining, with a low credit balance alert for all customers with an initial sign-up credit.
Create an alert
CREATE ALERTS ON BEHALF OF YOUR CUSTOMERSYour 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 many alert types. These generally fall into two categories: Commitment/Credit alerts and Spend alerts. Each alert type is measured either once per day or in real time as usage is sent to Metronome. 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.)

​
Commitment and credit alerts

SEPARATE ALERTS FOR COMMITS AND CREDITSThis category of alerts evaluates commitments or credits separately, except for the Low credit and commitment balance alert, which alerts on the sum of both.

​
Low remaining days in credit/Low remaining days in commitment

This alert type sets a threshold for the number of days remaining on a particular credit or commitment. If multiple sets of credits or commits exist for a customer, the alert evaluates each of them independently and sends separate notifications as each credit or commit reaches the threshold. This alert type is measured once a day.

​
Low credit balance reached/Low commitment 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 credit or commit balance for the credit type reaches or goes below your set threshold. If multiple credits or commits exist for a customer, the alert sums up the remaining balances across all credits or commitments to compare against the threshold. This alert type is measured in real time as usage is sent to Metronome.

​
Low remaining credit percentage/Low remaining commitment 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 credits or commits for that credit type reaches or goes below your set threshold. This alert type is measured in real time as usage is sent to Metronome. The low remaining percentage alert only takes into account active credits or commits. The alert calculation automatically excludes expired credits. Low credit balance alerts by default apply to the total credit balance on a customer.
ALERT ON SPECIFIC CREDITS OR COMMITSTo alert on a specific credit or commit, set a custom field on the object in Metronome and use advanced filters to alert only on commits with that specific custom field value.

​
Low credit and commitment balance reached

This alert type sets a threshold on the remaining balance across a customer’s set of prepaid commitments, postpaid commitments, and credits. If multiple credits and commitments exist for a customer, the alert sums up the remaining balances across all credits and commitments to compare against the threshold. This alert type is measured in real time as usage is sent to Metronome.

​
Spend alerts

Spend alerts are alerts tied to a billing period, like quarterly or monthly. Monthly spend alerts fire for spend in the current month, regardless of the billing period.

​
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 usage-based spend prior to commit and credit drawdown for their current billing period reaches or goes above your set threshold. This alert evaluates against the sum of all usage-based charges for a particular customer, including usage drawdowns on credits and commits. This alert type is measured in real time as usage is sent to Metronome. Optionally, use the group_values parameter with this alert type to evaluate only usage associated with a specific group key:group value pair.
DOES NOT INCLUDE CREDIT PURCHASESCredit and commit purchases are not factored into a customer’s spend threshold alert. For example, if the threshold is set at $10,000, an actual billing spend of $7,000 plus a credit purchase of $3,000 does not trigger the alert.
SPEND ALERTS AND CUSTOM PRICING UNITSSpend alerts are evaluated only against direct spend in a specific credit type. A spend alert threshold configured for a currency always evaluates to ok if you are using a custom pricing unit for a customer’s line items.To avoid this, configure spend alert thresholds to use the same pricing unit as the line items on a customer’s invoice.
ALERTING ON SPECIFIC CONTRACTSTo alert on a specific contract, set a custom field on the contract in Metronome and use advanced filters to alert only on contracts with that specific custom field value.

​
Invoice total reached

This alert type sets a threshold for an invoice total and sends a notification if any of the customer’s active invoices reaches or exceeds the configured threshold. Note that the invoice total used is the net total after any credits, commits, or other adjustments have been applied. The alert evaluates each active invoice separately. This alert type is measured in real time as usage is sent to Metronome. There are two filtering criteria for this alert type:
  • Currency (required), only invoices in the specified currency are evaluated.
  • Invoice type (optional), only invoices of the specified type are evaluated. Example invoice types include usage invoices, scheduled invoices, and credit purchase invoices. If unspecified, all invoice types are evaluated.

​
Usage Alerts

​
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 reaches or goes above your set threshold. The current billing period for a customer is calculated by taking the earliest start date and the latest end date across all active invoices. This alert type is measured in real time as usage is sent to Metronome.

​
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 ALERTSDespite 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 ALERTTo update an alert—for example, to change the threshold—first archive it (using the Metronome app or API), then re-create it 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, contract, commitments, and credits 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 starts or expires) are evaluated at 00:00UTC on the specified date of transition. Daily alert types (such as low remaining days in a commitment or low remaining credit percentage and usage threshold) are evaluated at 04:00UTC every day. Spend threshold and credit threshold alerts have notifications sent within minutes of that condition being met. Daily alerts are evaluated at 04:00UTC and sent out shortly thereafter with a 24-hour SLA.

​
Forcing alert re-evaluation

Alerts are continuously evaluated, but Metronome only triggers notifications when an alert changes state. This could lead to unintended behavior if your systems reset their state in response to changes in a customer’s plan and are expecting an alerts re-notification. In those situations you can force a re-evaluation of an alert for a customer through the /customer-alerts/reset endpoint. This puts the alert into the ok state for that customer and enqueue it to be re-evaluated as if customer metadata had changed.

​
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.
ALERT RESOLUTION NOTIFICATIONTalk to your Metronome representative if you’d like to also receive webhook notifications when an alert is resolved.
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_alarm and 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 Metronome app for any recent changes (e.g., a new commit 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 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

​
Webhook Payload Examples

The below shows example webhook payloads for each alert type. 
{  
  "id": "3dbaab98-45e9-4b55-864c-4650497d80d7",  
  "properties": {  
    "customer_id": "ac39ecc3-87ee-4d58-8ec0-24041464a5dd",  
    "alert_id": "445b849e-1366-4580-a6cc-f488e27c059f",  
    "timestamp": "2024-10-07T15:08:44.865Z",  
    "threshold": 20000,  
    "alert_name": "Commit balance low",  
    "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",  
    "remaining_balance": 5000,  
    "triggered_by": "usage"  
  },  
  "type": "alerts.low_remaining_commit_balance_reached"  
}