Event | OpenMeter

#What is an Event?

An event results from a match occurring to a Rule. The events are delivered to the target specified by the Channels.

The event has two distinct views. The channel's underlying implementation will send the event to the target. The payloads are described below and in OpenMeter's OpenAPI spec.

Events can also be queried on the OpenMeter API (/v1/api/notification/events). This view contains the payload received by the channel but includes extended information on the event, such as delivery status and annotations.

#Event payloads

The event payload is the data received from the channel.

#Balance Notification Event

The balance notification event will have the type of entitlements.balance.threshold.

An example event payload for an event triggered by reaching a numeric threshold of 2000 on an entitlement is the following:

{
  "data": {
    "entitlement": {
      "createdAt": "2024-08-22T08:43:14.154903Z",
      "currentUsagePeriod": {
        "from": "2024-08-22T08:43:00Z",
        "to": "2024-08-29T08:43:00Z"
      },
      "featureId": "01J5WKAM9FJ4621ARR641JS17Q",
      "featureKey": "llm_tokens",
      "id": "01J5WM25BAXSCBKG2D9NDYJB6S",
      "isSoftLimit": false,
      "isUnlimited": false,
      "issueAfterReset": 2500,
      "issueAfterResetPriority": 1,
      "lastReset": "2024-08-22T08:43:00Z",
      "measureUsageFrom": "2024-08-22T08:43:00Z",
      "preserveOverageAtReset": false,
      "subjectKey": "notification-test-2",
      "type": "metered",
      "updatedAt": "2024-08-22T08:43:14.154904Z",
      "usagePeriod": {
        "anchor": "2024-08-22T08:43:00Z",
        "interval": "WEEK"
      }
    },
    "feature": {
      "createdAt": "2024-08-22T08:30:23.023643Z",
      "id": "01J5WKAM9FJ4621ARR641JS17Q",
      "key": "llm_tokens",
      "meterSlug": "tokens_total",
      "name": "llm_tokens",
      "updatedAt": "2024-08-22T08:30:23.023644Z"
    },
    "subject": {
      "currentPeriodEnd": null,
      "currentPeriodStart": null,
      "displayName": null,
      "id": "01J5WM256DNGXKG2N17AHVXKTD",
      "key": "notification-test-2",
      "metadata": {},
      "stripeCustomerId": null
    },
    "threshold": {
      "type": "NUMBER",
      "value": 2000
    },
    "value": {
      "balance": 254,
      "hasAccess": true,
      "overage": 0,
      "usage": 2369
    }
  },
  "id": "01J5WQFP993XTYM1HAZH3SHP2G",
  "timestamp": "2024-08-22T09:43:03.209883Z",
  "type": "entitlements.balance.threshold"
}

The event contains contextual data. The receiving end can use this contextual data, ensuring that it doesn't have to make additional calls to the OpenMeter APIs to gather it.

#Events API

Events API provides access to the historical list of events sent, including additional data such as delivery status.

#Delivery status

The delivery status is a log of delivery attempts for a specific event. It can be used to troubleshoot delivery attempts.

    "deliveryStatus": [
        {
            "channel": {
                "id": "01J5WK8KGY9PZBY83981H47WXB",
            },
            "state": "SUCCESS",
            "updatedAt": "2024-08-22T09:42:55.567159Z"
        }
    ],

OpenMeter supports the following delivery status states:

State	Reason
PENDING	The event has been created, but the sending hasn't been started yet
SENDING	The event is being sent
SUCCESS	The event has been delivered succesfully
FAILED	Event delivery failed

#Annotations

Annotations is a object of key value string pairs, containing additional metadata information for easier event search. They can be used to understand the relation of an event to other entities.

We are supporting the following annotations:

Key	Value
event.feature.key	For events specific to a feature, the feature key or missing if not applicable
event.feature.id	For events specific to a feature, the feature id or missing if not applicable
event.subject.key	For events specific to a subject, the subject key or missing if not applicable
event.subject.id	For events specific to a subject, the subject id or missing if not applicable or if subject id is not available

The annotation information is only available on the OpenMeter events API. OpenMeter uses other annotation keys for its internal state management. We suggest only using the documented annotations, as others are subject to change without notice.