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 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 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 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 credits

This 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 grant 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 credit grants 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 credit grants or commits. The alert calculation automatically excludes expired credits. Low credit balance alerts by default apply to the total credit balance on a customer.

Alerting on specific credit grants or commits

To alert on a specific credit grant 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 in to Metronome.

Spend alerts​

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 throughout the day.

Does not include credit purchases

Credit 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 units

Spend 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.

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 in 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.

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 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 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 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 notification

Talk 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_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 Metronome app 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  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": "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"
}
{
  "id": "6500fedc-6914-4e44-8f64-f4e9edeaa23f",
  "properties": {
    "customer_id": "ac39ecc3-87ee-4d58-8ec0-24041464a5dd",
    "alert_id": "f1af58df-c6be-4ddf-a0f0-49d366247002",
    "credit_id": "ad178b76-334f-43a2-87aa-3a951fd939d4",
    "threshold": 5,
    "alert_name": "Days in contract credit",
    "remaining_days": 5
  },
  "type": "alerts.low_remaining_days_for_contract_credit_segment_reached"
}
© 2024 Metronome. All rights reserved.
CareersBlogLog in