Notifications

Metering & Billing Notifications let you configure automated webhook alerts that trigger when specific usage thresholds or billing events occur. Instead of polling for usage data, you define rules that trigger notification events to a channel of your choice when conditions are met.

The following table describes the use cases for notifications:

The Metering & Billing Notifications system is built around three entities:

 
flowchart LR
    Rule["Rule
(when to trigger)"]
    Channel["Channel
(where to send)"]
    Event["Event
(the notification sent)"]

    Rule --> Event
    Event --> Channel
  

1. Rule: Defines the condition that triggers a notification. When the condition is met, Metering & Billing sends a notification event to all channels attached to the rule.
2. Event: The notification payload delivered to your channel when a rule triggers. Events include details about the customer, entitlement, and the threshold that was crossed.
3. Channel: Defines where to send notifications. Currently, Metering & Billing supports webhook channels. A single channel can be referenced by multiple rules.

A channel defines a delivery destination for notification events. Metering & Billing supports webhook channels, which send an HTTP POST request with a JSON payload to a URL of your choice.

Use webhook channels to:

• Integrate with Slack incoming webhooks
• Trigger threshold-based email alerts via your email provider
• Call an internal API to cut off a customer’s access
• Forward events to your data warehouse or alerting platform

Create a channel

To create a webhook channel in Konnect:

1. In the Konnect sidebar, click Metering & Billing.
2. In the Metering & Billing sidebar, click Settings.
3. Click the Notifications tab.
4. Click Create Channel.
5. In the Name field, enter a name for the channel.
6. In the URL field, enter the webhook URL to deliver notifications to.
7. (Optional) Add custom HTTP headers if your endpoint requires authentication.
8. Click Save.

Verify webhook requests

When exposing a webhook endpoint, make sure the sender is authenticated before you process the payload. Metering & Billing lets you add custom HTTP headers when you create the channel. A common pattern is to configure a shared secret in a custom header, for example Authorization: Bearer <secret> or X-Webhook-Secret: <secret>, and validate that value in your webhook handler for every delivery.

Reject requests with a missing or invalid authentication header by returning a 400 or 401 response, and only process the notification after the header value matches the secret you configured on the channel.

A rule defines the condition that triggers a notification. When the condition is met, Metering & Billing delivers a notification event to the channels specified in the rule.

Metering & Billing supports the following rule types:

Notifications for gathering invoices are not currently supported.

Entitlement balance threshold rules

Use this rule type to trigger notifications when a customer’s metered entitlement usage reaches a threshold. This is the primary rule type for implementing entitlement enforcement and customer warnings.

To create an entitlement balance threshold rule:

1. In the Konnect sidebar, click Metering & Billing.
2. In the Metering & Billing sidebar, click Settings.
3. Click the Notifications tab.
4. Click Create Rule.
5. In the Name field, enter a name for the rule.
6. From the Type dropdown menu, select “Entitlement balance threshold”.
7. From the Channels dropdown menu, select one or more channels to deliver the notification to.
8. (Optional) From the Features dropdown menu, select features to scope the rule to.
9. From the Thresholds settings, add one or more thresholds. Each threshold triggers a separate notification event.
10. Click Save.

When a rule condition is met, Metering & Billing delivers a notification event as an HTTP POST request to all channels attached to the rule. The event payload is a JSON object containing the following information:

Each notification event has a delivery state:

You can view past notification events in Konnect by navigating to Metering & Billing > Settings > Notifications and clicking the name of the rule.

Metering & Billing tracks entitlement balances and triggers notification events when thresholds are crossed, but it does not automatically block API traffic when a customer’s entitlement is exhausted.

To enforce entitlement limits today, configure a webhook notification rule and handle the incoming event in your own system:

1. Create a webhook channel pointing to an endpoint you control.
2. Create an entitlement balance threshold rule with a threshold at 100% for the feature you want to enforce.
3. In your webhook handler, take action when the event is received. For example:
   • Remove the Consumer from a Kong Gateway Consumer Group that has access to the API.
   • Return a 403 Forbidden response from your application layer.
   • Update a feature flag in your system to disable access for the customer.
4. (Optional) Add a second threshold at 80% to send a warning to the customer before access is cut off.