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.

Does not include credit purchases

Credit 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 will always evaluate 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.

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.

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 or other adjustments have been applied. The alert will be evaluated separately for each of the customer's currently active invoices.

There are two filtering criteria for this alert type:

  • Currency (required): Only invoices in the specified currency will be evaluated.
  • Invoice type (optional): Only invoices of the specified type will be evaluated. Example invoice types include usage invoices, scheduled invoices, and credit purchase invoices. If unspecified, all invoice types will be evaluated.

The webhook payload for this alert type is as follows:

{
  "id": "a1ea9901-46e3-4888-acf1-4d9adaec4cdf",
  "properties": {
    "customer_id": "59071db8-0502-4255-b1ac-dfebf5d9e1e9",
    "alert_id": "2c1bf7d7-d981-4591-9f45-d0c95789c5e3",
    "timestamp": "2024-06-05T00:41:19.860839Z",
    "threshold": 1000,
    "alert_name": "<alert name>",
    "invoice_id": "6644b5ec-394a-4d07-a037-e2827a0af4be",
    "invoice_total": 1600,
    "triggered_by": "usage"
  },
  "type": "alerts.invoice_total_reached"
}

This alert type is measured throughout the day.

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 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 will only trigger 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 will put 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 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
© 2024 Metronome. All rights reserved.
CareersBlogLog in