Copy page

Common workflows

Subscribe to events

Use this workflow to subscribe to UtilityCloud events.

Events are used to keep external systems up to date when data changes in UtilityCloud. Instead of repeatedly polling the API, an external system can receive events and react to changes as they happen.

When to use

Use this workflow when an external system needs to stay synchronized with UtilityCloud.

Typical use cases include:

• keeping a CRM system updated when customers, accounts, contacts, or contracts change
• updating an ERP, data warehouse, or reporting system when relevant business data changes
• reacting to contract lifecycle changes
• reacting to product or offer changes
• tracking changes to Accounting Points
• receiving event-driven updates instead of polling API endpoints

Event delivery

Events are delivered asynchronously.

The receiving system should be designed to handle:

• duplicate events
• delayed events
• events arriving out of strict business order
• retries
• temporary delivery failures
• event schema changes over time

Each event should be processed idempotently. This means that processing the same event more than once should not create duplicate or incorrect data in the receiving system.

Event preparation

Before events can be delivered, the receiving party must provide the required event delivery configuration.

The typical setup is:

1. Create an Azure Service Bus namespace in your own Azure subscription.
2. Create a queue or topic for receiving events.
3. Send the connection string to UtilityCloud support.
4. UtilityCloud enables forwarding of events to the configured queue or topic.

Event types

UtilityCloud can emit events for several business objects.

Typical event categories include:

Event category	Description
Customer events	Events related to customer creation, update, archiving, or other customer lifecycle changes.
Account events	Events related to Account creation, update, archiving, erasure, or transfer.
Accounting Point events	Events related to Accounting Point creation or update.
Contact events	Events related to contact creation or update.
Contract events	Events related to contract creation, update, replacement, reversion, erasure, or lifecycle changes.
Offer events	Events related to offers.
Product events	Events related to product updates.
Ignored events	Events that were ignored, including the reason and related aggregates.

Event structure

Events are normally structured with a common event envelope and a resource-specific payload.

A typical event contains:

Section	Description
Header	Metadata about the event.
Payload	The business data for the event.
Footer	Optional additional event information.

Header

The Header contains metadata used for routing, tracing, versioning, and processing.

Typical header fields include:

Field	Description
Source	Source system or component that created the event.
EventName	Name of the event.
EventCategory	Category of the event.
EventID	Unique event id.
Version	Event version.
Origin	Origin of the event.
TenantID	Tenant identifier.
CorrelationID	Correlation id used for tracing related operations.
EventCreatedDate	Date and time when the event was created.
ReferenceID	Optional reference id.
Receiver	Optional receiver information.
ServiceType	Optional Service Type context.
RetryCount	Optional retry count.

Payload

The Payload contains the business object or business change represented by the event.

Examples:

• a Customer event contains Customer data
• an Account event contains Account data
• a Contract event contains Contract data
• an Accounting Point event contains Accounting Point data
• an Offer event contains Offer data

The exact payload structure depends on the event type.

Example event structure

Code
{
  "Header": {
    "Source": "UtilityCloud",
    "EventName": "ContractUpdated",
    "EventCategory": "Contract",
    "EventID": "4b7bca5f-0cc2-42c1-83f4-45a71b3b7d58",
    "Version": "1",
    "Origin": "CM",
    "TenantID": "tenant-id",
    "CorrelationID": "7f4b0b8e-6d8b-4a72-9f2c-2f2d1fd8a001",
    "EventCreatedDate": "2026-06-01T12:00:00Z",
    "ServiceType": "NO_EL"
  },
  "Payload": {
    "Contract": {
      "Guid": "2a177e80-d6e8-44fb-a4ee-9c327f92f283",
      "Status": "Active"
    }
  },
  "Footer": {
    "RequestedBy": "external-system"
  }
}

Event processing recommendations

When consuming events, the receiving system should:

• store the EventID to avoid processing the same event more than once
• use CorrelationID for tracing related operations
• use resource identifiers from the payload to update the correct external record
• handle events that arrive later than expected
• handle missing related data by retrieving the current state from the API if needed
• avoid relying on event order as the only source of truth
• log failed event processing for retry or manual investigation

Synchronization pattern

A common integration pattern is:

1. Perform an initial data load using relevant API endpoints.
2. Store the UtilityCloud GUIDs and external identifiers.
3. Subscribe to relevant events.
4. Process incoming events to keep the external system updated.
5. Use API lookups when the event payload does not contain all information needed by the receiving system.

Notes

Events are intended for synchronization and notification of changes.

The event stream should not be treated as the only source of truth. If the receiving system needs the latest complete state of a resource, retrieve the resource through the API.

Event availability and scope depend on tenant configuration and agreed integration setup.

UtilityCloud must configure event forwarding before events are delivered.

Related workflows

Code
GET /v1/cm/customers?limit={limit}&page={page}
GET /v1/cm/accounts?limit={limit}&page={page}
GET /v1/cm/accountingpoints?limit={limit}&page={page}
GET /v1/cm/contracts?limit={limit}&page={page}
GET /v1/pm/products