# Set up usage-based alerts

Set up an alert for when a customer exceeds a usage threshold.

The new Usage Analytics API lets you build analytics dashboards for your end users. [Request to join the preview.](https://docs.stripe.com/billing/subscriptions/usage-based/alerts.md#meter_event_filtering_beta_preview)

### Interested in getting early access to spend and credit balance alerts

Enter your email to request access.

```bash
curl https://docs.stripe.com/preview/register \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Referer: https://docs.stripe.com/billing/subscriptions/usage-based/alerts" \
  -d '{"email": "EMAIL", "preview": "meter_event_filtering_beta_preview"}'
```

Set up alerts to get notified when customers exceed meter usage thresholds, or to trigger an invoice when customers reach a specific billing threshold. You can create alerts that apply to either specific customers or all customers.

## Before you begin

You must [create a meter](https://docs.stripe.com/billing/subscriptions/usage-based/implementation-guide.md#create-meter) before you create an alert.

## Create usage alerts 

You can configure [alerts](https://docs.stripe.com/api/billing/alert/create.md) using the Stripe Dashboard or API.

For example, you can create a one-time alert for customers that triggers when they reach 100 API calls. When a customer reaches 100 API calls, you receive a webhook notifying you that the customer has exceeded the threshold.

Stripe provides a usage alert type called `One-time per-customer usage alert`. This alert triggers when a customer exceeds the specified usage level for the first time, and only triggers one time per customer, regardless of future usage.

#### Dashboard

1. On the [Billing Alerts](https://dashboard.stripe.com/settings/billing/alerts) page, click **Create alert**.

2. On the **New alert** page, do the following:

   - For **Name**, enter the name for your alert. This isn’t visible to customers.
   - Under **Alert type**, select the meter that you want to set up alerts for.
   - For **Unit threshold**, set the usage amount to reach for an alert to trigger.
   - (Optional) Under **Application**, select **Specific customer** and the customer name, if you want the alert to apply only to that customer. Otherwise, leave the default of **Any customer** to configure the alert for all customers.
   - Click **Create alert**.

#### API

```curl
curl https://api.stripe.com/v1/billing/alerts \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "title=Sample alert" \
  -d alert_type=usage_threshold \
  -d "usage_threshold[filters][0][type]=customer" \
  -d "usage_threshold[filters][0][customer]={{CUSTOMER_ID}}" \
  -d "usage_threshold[meter]={{METER_ID}}" \
  -d "usage_threshold[gte]=100" \
  -d "usage_threshold[recurrence]=one_time"
```

## Listen for webhooks 

After you configure an alert and start sending usage for that meter, you can listen for *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests). These events trigger when there’s a status change in Stripe, such as creating a new subscription or invoice.

In your application, set up an HTTP handler to accept a POST request containing the webhook event, and verify the signature of the event.

#### Ruby

```ruby

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

post '/webhook' do
# You can use webhooks to receive information about asynchronous payment events.
# For more information, see https://stripe.com/docs/webhooks.
webhook_secret = ENV['STRIPE_WEBHOOK_SECRET']
payload = request.body.read
if !webhook_secret.empty?
  # Retrieve the event by verifying the signature using the raw body and secret, if webhook signing is configured.
  sig_header = request.env['HTTP_STRIPE_SIGNATURE']
  event = nil

  begin
    event = Stripe::Webhook.construct_event(
      payload, sig_header, webhook_secret
    )
  rescue JSON::ParserError => e
    # Invalid payload
    status 400
    return
  rescue Stripe::SignatureVerificationError => e
    # Invalid signature
    puts '⚠️  Webhook signature verification failed.'
    status 400
    return
  end
else
  data = JSON.parse(payload, symbolize_names: true)
  event = Stripe::Event.construct_from(data)
end
# Get the type of webhook event sent, which checks the status of PaymentIntents.
event_type = event['type']
data = event['data']
data_object = data['object']

if event_type == 'billing.alert.triggered'
  # If the meter exceeds the defined threshold in the alert
  # Only triggers if it matches to at least one Stripe customer.
end

content_type 'application/json'
{ status: 'success' }.to_json
end
```

During development, use the Stripe CLI to [monitor webhooks and forward them to your application](https://docs.stripe.com/webhooks.md#test-webhook). Run the following in a new terminal while your development app is running:

#### curl

```bash
stripe listen --forward-to localhost:4242/webhook
```

For production, set up a webhook endpoint URL in the Dashboard, or use [Webhook Endpoints](https://docs.stripe.com/api/webhook_endpoints.md).

## Limitations 

Consider the following limitations for usage alerts:

- We evaluate alerts when you report usage data after you create the alert. However, the evaluation includes usage data that you reported before you created the alert.
- You can create a maximum of 25 alerts for each combination of a specific meter and customer. However, you can create an alert for a specific meter for each of your customers.
- Alerts currently don’t work with test clocks.