> ## Documentation Index > Fetch the complete documentation index at: https://docs.m3ter.com/llms.txt > Use this file to discover all available pages before exploring further. # Object Definitions and API Calls This topic sets out in detail the objects that feature in the Events and Notifications framework. The relevant API calls you can use with each object are noted together with examples of object JSON schemas: * [Event Types](/guides/alerts-events-and-notifications/utilizing-events-and-notifications/object-definitions-and-api-calls#event-types) * [Event Fields](/guides/alerts-events-and-notifications/utilizing-events-and-notifications/object-definitions-and-api-calls#event-fields) * [Events](/guides/alerts-events-and-notifications/utilizing-events-and-notifications/object-definitions-and-api-calls#events) * [Notification Rule](/guides/alerts-events-and-notifications/utilizing-events-and-notifications/object-definitions-and-api-calls#notification-rule) * [Outgoing Webhooks and Credentials](/guides/alerts-events-and-notifications/utilizing-events-and-notifications/object-definitions-and-api-calls#outgoing-webhooks-and-credentials) * [Integration Configuration for Notification](/guides/alerts-events-and-notifications/utilizing-events-and-notifications/object-definitions-and-api-calls#integration-configuration-for-notification) **Tip: API Calls?** Please see the [Events](/api/events/introduction), [Notifications](/api/notifications/introduction), and [Integrations](/api/integrations/introduction) sections of our API Reference Docs for relevant API calls. ## Event Types *Events Types* cover: * Many of the common configuration and billing objects: * For each object there are three Event Types - for when the configuration or billing object is **created**, **updated**, or **deleted**. * The integration **External Mapping** entity - whenever one is **created**, **updated**, or **deleted**. * Some integration errors. These are surfaced in the Console on the **Integrations>Events** page. See [Reviewing and Resolving Integration Events](/guides/integrations/setting-up-integrations/reviewing-and-resolving-integration-events). * Some ingest validation failures. These are surfaced in the Console on the **Usage>Ingest Events** page. See [Reviewing and Resolving Ingest Events](/guides/billing-and-usage-data/submitting-usage-data/reviewing-and-resolving-ingest-events). * Data export job failures. You can return these using the [List EventResponse](/api/events/list-eventresponse) API endpoint. See [Following-Up on Failed Export Jobs](/guides/data-exports/reviewing-export-jobs#following-up-on-failed-export-jobs) for more details. * Scheduled Events you can set up for your specific Organization. See [Working with Scheduled Events](/guides/alerts-events-and-notifications/utilizing-events-and-notifications/working-with-scheduled-events). ### API Call To obtain a list of the Event Types currently available for configuring Notifications, you can use the [List Notification Events](/api/events/list-notification-events) API call: `GET https://api.m3ter.com/organizations/{orgId}/events/types` The return lists the available Event Types: ```json theme={null} { "events": [ "billing.balance.created", "billing.balance.deleted", "billing.balance.updated", "billing.balanceamount.created", "billing.balanceamount.deleted", "billing.balanceamount.updated", "billing.bill.created", "billing.bill.deleted", "billing.bill.updated", "billing.billconfig.created", "billing.billconfig.deleted", "billing.billconfig.updated", "billing.billjob.created", "billing.billjob.deleted", "billing.billjob.updated", "billing.charge.created", "billing.charge.deleted", "billing.charge.updated", "billing.counteradjustment.created", "billing.counteradjustment.deleted", "billing.counteradjustment.updated", "billing.scheduledbalancecharge.created", "billing.scheduledbalancecharge.deleted", "billing.scheduledbalancecharge.updated", "billing.scheduledbalancetransaction.created", "billing.scheduledbalancetransaction.deleted", "billing.scheduledbalancetransaction.updated", "billing.statementjob.created", "billing.statementjob.deleted", "billing.statementjob.updated", "configuration.account.created", "configuration.account.deleted", "configuration.account.updated", "configuration.accountplan.created", "configuration.accountplan.deleted", "configuration.accountplan.updated", "configuration.aggregation.created", "configuration.aggregation.deleted", "configuration.aggregation.updated", "configuration.alert.created", "configuration.alert.deleted", "configuration.alert.updated", "configuration.commitment.created", "configuration.commitment.deleted", "configuration.commitment.updated", "configuration.compoundaggregation.created", "configuration.compoundaggregation.deleted", "configuration.compoundaggregation.updated", "configuration.contract.created", "configuration.contract.deleted", "configuration.contract.updated", "configuration.counter.created", "configuration.counter.deleted", "configuration.counter.updated", "configuration.counterpricing.created", "configuration.counterpricing.deleted", "configuration.counterpricing.updated", "configuration.creditreason.created", "configuration.creditreason.deleted", "configuration.creditreason.updated", "configuration.customfield.created", "configuration.customfield.deleted", "configuration.customfield.updated", "configuration.lookuptable.created", "configuration.lookuptable.deleted", "configuration.lookuptable.updated", "configuration.lookuptablerevision.created", "configuration.lookuptablerevision.deleted", "configuration.lookuptablerevision.updated", "configuration.lookuptablerevisiondatajob.created", "configuration.lookuptablerevisiondatajob.deleted", "configuration.lookuptablerevisiondatajob.updated", "configuration.meter.created", "configuration.meter.deleted", "configuration.meter.updated", "configuration.metergroup.created", "configuration.metergroup.deleted", "configuration.metergroup.updated", "configuration.organization.created", "configuration.organization.deleted", "configuration.organization.updated", "configuration.organizationconfig.created", "configuration.organizationconfig.deleted", "configuration.organizationconfig.updated", "configuration.plan.created", "configuration.plan.deleted", "configuration.plan.updated", "configuration.plangroup.created", "configuration.plangroup.deleted", "configuration.plangroup.updated", "configuration.plangrouplink.created", "configuration.plangrouplink.deleted", "configuration.plangrouplink.updated", "configuration.plantemplate.created", "configuration.plantemplate.deleted", "configuration.plantemplate.updated", "configuration.pricing.created", "configuration.pricing.deleted", "configuration.pricing.updated", "configuration.pricingband.created", "configuration.pricingband.deleted", "configuration.pricingband.updated", "configuration.product.created", "configuration.product.deleted", "configuration.product.updated", "configuration.transactiontype.created", "configuration.transactiontype.deleted", "configuration.transactiontype.updated", "dataexport.job.failure", "dataexport.job.success", "ingest.validation.failure", "integration.authentication.error", "integration.disabled.error", "integration.externalmapping.created", "integration.externalmapping.deleted", "integration.externalmapping.updated", "integration.missingaccountmapping.error", "integration.perform.error", "integration.validation.error" ] } ``` * Note that if you've set up any Scheduled Events for your Organization, these will be included in the response to this call. The format for this type of Event is: * **scheduled**.*\*.*\* * For example: `"scheduled.bill.endDateEvent"` * See [Working with Scheduled Events](/guides/alerts-events-and-notifications/utilizing-events-and-notifications/working-with-scheduled-events) for more details. ## Event Fields *Fields* are available for each Event Type to make any calculations on the schema dynamic and forward compatible. ### API Call To obtain a list of the fields for an Event Type, you can use the [List Event Fields](https://docs.m3ter.com/api/events/list-event-fields) call: `GET https://api.m3ter.com/organizations/{orgId}/events/fields` #### Query Parameters `eventName (String)` - the name of the Event Type to filter by. Here we've queried to get the field for the `configuration.commitment.created` Event Type - `new` represents the attributes the new object has: ```json theme={null} { "events": { "configuration.commitment.created": { "new.accountCode": "string", "new.accountId": "string", "new.accountingProductId": "string", "new.amount": "double", "new.amountFirstBill": "double", "new.amountPrePaid": "double", "new.amountSpent": "double", "new.billEpoch": "string", "new.billingInterval": "int", "new.billingOffset": "int", "new.billingPlanId": "string", "new.commitmentFeeBillInAdvance": "boolean", "new.commitmentFeeDescription": "string", "new.commitmentUsageDescription": "string", "new.contractId": "string", "new.currency": "string", "new.customFields": "map", "new.endDate": "string", "new.feeDates": "array", "new.id": "string", "new.overageDescription": "string", "new.overageSurchargePercent": "double", "new.productIds": "array", "new.startDate": "string" } } } ``` Here we’ve queried to get the fields for the `configuration.commitment.updated` Event Type, where `new` is the updated object and `old` is the previous state of the object: ```json theme={null} { "events": { "configuration.commitment.updated": { "new.accountCode": "string", "new.accountId": "string", "new.accountingProductId": "string", "new.amount": "double", "new.amountFirstBill": "double", "new.amountPrePaid": "double", "new.amountSpent": "double", "new.billEpoch": "string", "new.billingInterval": "int", "new.billingOffset": "int", "new.billingPlanId": "string", "new.commitmentFeeBillInAdvance": "boolean", "new.commitmentFeeDescription": "string", "new.commitmentUsageDescription": "string", "new.contractId": "string", "new.currency": "string", "new.customFields": "map", "new.endDate": "string", "new.feeDates": "array", "new.id": "string", "new.overageDescription": "string", "new.overageSurchargePercent": "double", "new.productIds": "array", "new.startDate": "string", "old.accountCode": "string", "old.accountId": "string", "old.accountingProductId": "string", "old.amount": "double", "old.amountFirstBill": "double", "old.amountPrePaid": "double", "old.amountSpent": "double", "old.billEpoch": "string", "old.billingInterval": "int", "old.billingOffset": "int", "old.billingPlanId": "string", "old.commitmentFeeBillInAdvance": "boolean", "old.commitmentFeeDescription": "string", "old.commitmentUsageDescription": "string", "old.contractId": "string", "old.currency": "string", "old.customFields": "map", "old.endDate": "string", "old.feeDates": "array", "old.id": "string", "old.overageDescription": "string", "old.overageSurchargePercent": "double", "old.productIds": "array", "old.startDate": "string" } } } ``` Note that in contrast to a new Event, an updated Event contains fields for both `new` and `old` values, where the `old` field values are those from the previous version and `new` are the updated version values. Correspondingly, if you query for `configuration.commitment.deleted` Event, the response will show only `old` field values, which are the values at point of deletion. **Warning:** `customFields`**show!** Some Event types will show `customFields` even though the specific billing or configuration object the Event is for doesn't yet have the custom fields functionality implemented. For these Events, their `customFields` values will not be populated until such time as the custom fields functionality is implemented for them. ## Events *Events* are instances of available Event Types. They describe a state change in the system. ### API Call You can use the [List Event Response](/api/events/list-eventresponse) call to obtain a list of all Events and apply a filter or `GET` by id. #### Query Parameters * `eventName (String)` -  the name of the Event to filter by. * `notificationId (String)` -  the notification id to filter by. * `accountId (String)` -  the account Id that generated the Event to filter by. * `eventType (String)` -  the name of the Event to filter by. * `notificationCode (String)` -  the code of the notification to filter by. * `resourceId (String)` -  the id of the resource that triggered the Event to filter by. * `ids(String)` -  List of ids to filter by. **NOTE:** cannot be used with other filters. * `nextToken (String)` -  next page token. * `pageSize (int)` - page size. For example, if we query by `eventName`: `GET https://api.m3ter.com/organizations/{orgId}/events?eventName=configuration.commitment.created` In this example, we see that there is a single `configuration.commitment.created` Event for the Organization: ```json theme={null} { "data": [ { "id": "9cb46d85-7cb6-4637-80a1-d4ec38e4ab30", "eventName": "configuration.commitment.created", "eventTime": "2022-10-28T13:54:49.557Z", "m3terEvent": { "eventData": { "newDto": { "commitmentFeeDescription": "", "endDate": "2024-12-31", "billingInterval": 1, "orgId": "396d788d-5174-XXXX-9d69-YYYY4671fc33", "overageSurchargePercent": 5.0, "overageDescription": "", "currency": "USD", "id": "480d317e-2030-416b-b64b-c07577c418b4", "amountSpent": 0.0, "accountCode": "doetech_premium", "amount": 15000.0, "billingOffset": 0, "lastModifiedBy": "USER_810e3a43-XXXX-4dab-YYYY-470977405b58", "billingPlanId": "0409e75a-8a87-43de-aa58-fc6ec823ce37", "version": 1, "accountId": "1cf2a754-476c-498c-b05a-7d41abfc404d", "dtCreated": "2022-10-28T13:54:48.081781Z", "amountPrePaid": 0.0, "productIds": [ "bec371ef-dbad-4e73-a56a-dadecff2287c" ], "createdBy": "USER_810e3a43-XXXX-4dab-YYYY-470977405b58", "contractId": "68595d6d-261f-496b-bf88-51fc7d2b5ccc", "commitmentUsageDescription": "", "startDate": "2023-01-01", "dtLastModified": "2022-10-28T13:54:48.081781Z" } }, "eventTime": "2022-10-28T13:54:48.087Z", "eventName": "configuration.commitment.created" } } ], "nextToken": "MTY2MDMxNTYyNjQ1NCNERUxJTSNhNTIxMDQ0Zi0zMzA0LTQ0ZjEtYTBkYy05YzQyMjIzZGFhMWE=" } ``` ## Notification Rule Enables you to set up the rules for when a Notification gets triggered on the basis of an Event. ### API Calls You can use the API calls documented in the [Notifications](/api/notifications/introduction) section of our API Reference Docs - supports `POST`, `PUT`, `DELETE`, `GET `by id, or `GET` list verbs. Here's an example schema: ```json theme={null} { "id": "uuid", "version": 1, "name": "Commitment has under 10% remaining", "description": "Commitment amount fell below 10%", "eventName": "configuration.commitment.updated", "calculation": "(new.amountSpent >= ((new.amount*100)/90)) AND ((old.amountSpent <= ((old.amount*100)/90)) OR (old.amountSpent == null))", "code" : "under_10_percent", "active": true } ``` Some points to note for the Notification Rule schema: * `calculation` - is the key part, determining whether or not an Event will trigger a Notification. Please see the [Creating Calculations](/guides/alerts-events-and-notifications/utilizing-events-and-notifications/key-concepts-and-relationships#creating-calculations) section for more details on working with calculations for Notifications. * `active` - allows you to temporarily disable a Notification. * `eventName` - the calculation will be applied only on these specific events. To apply the same calculation over multiple events, multiple notification rules need to be created. **Tip: Creating Notification Rules in the Console?** For details on how to create and configure Notification Rules in the Console and go on to link Rules to integration Destinations to create Notification Integration Configurations, see the following topic in this section: [Creating, Managing, and Reviewing Notifications](/guides/alerts-events-and-notifications/utilizing-events-and-notifications/creating-managing-and-reviewing-notifications). ## Outgoing Webhooks and Credentials You can specify the endpoint for a Notification using an Outgoing Webhook. You can also specify credentials to be used with the Outgoing Webhook. Currently, only the `M3TER_SIGNED_REQUEST` credential format is supported: * `apiKey` - secret that will always be passed in “X-m3ter-apikey” header when the webhook is called. * `Secret` - secret that never leaves m3ter servers. Used as key to compute a SHA256 hash over: url + "|" + queryString + "|" + apiKey + "|"  + timestamp + "|" + body. * The timestamp will be passed in the request at “X-m3ter-timestamp”. ### API Calls You can use the webhooks Destination calls documented in the [Integrations](/api/integrations/introduction) section of our API Reference Docs - supports all `POST`, `PUT`, `DELETE`, `GET `by id or `GET `list verbs. For example [Create Webhook Destination](/api/integrations/create-webhook-destination): `POST https://api.m3ter.com/organizations/{orgId}/integrationdestinations/webhooks` Here's an example of the Destination schema: ```json theme={null} { "version": null, "url":"https://someurl.io", "credentials": { "version": null, "type": "M3TER_SIGNED_REQUEST", "apiKey": "apiKey", "secret": "a secret" // Only visible in first call } } ``` **Important!** As a security safeguard, you won’t be able to retrieve the secret once you’ve saved the credential. **Tip: Creating and Managing Outgoing Webhooks in the Console?** For details on how to create and configure Outgoing Webhooks in the Console and how to link them to Notifications and create Notification Integration configurations, see [Creating and Managing Outgoing Webhooks](/guides/integrations/setting-up-integrations/creating-and-managing-destinations). ## Integration Configuration for Notification When you connect a Notification Rule of entityType (=’Notification’) to an Outgoing Webhook as destination, you set up a *Notification Webhook* *Integration*. ### API Calls You can use the IntegrationConfig calls documented in the [Integrations](/api/integrations/introduction) section of our API Reference Docs - supports all `POST`, `PUT`, `DELETE`, `GET `by id or `GET `list verbs. Here's an example: ```json theme={null} { "entityType":"Notification", "entityId":"be2b3082-f660-42b0-8895-33fdebcce73c", "destination":"Webhook", "destinationId":"ff1767ca-5871-49dd-82c1-48fc78610d72" } ``` We use the ID from the notification created in the Notification Rule step, and the ID of the Integration Destination created.