OCIMessaging & Eventsintermediate

OCI Notifications & Events Guide

Build event-driven architectures with OCI Notifications (ONS) topics, subscriptions, Events rules, and serverless automation patterns.

CloudToolStack Team24 min readPublished Mar 14, 2026

Prerequisites

Understanding of event-driven architecture concepts
OCI account with notifications and events permissions

Introduction to OCI Notifications and Events

Oracle Cloud Infrastructure provides two complementary services for building event-driven architectures: the Notifications service (ONS) for delivering messages to subscribers, and the Events service for automatically detecting and responding to resource state changes. Together, these services form the backbone of automation, monitoring, and operational workflows in OCI.

The Notifications service uses a publish-subscribe model. You create topics, add subscriptions (email, SMS, HTTPS webhooks, PagerDuty, Slack, or OCI Functions), and then publish messages to those topics. Subscribers receive the messages through their configured channels. This is conceptually similar to AWS SNS or Azure Notification Hubs.

The Events service monitors OCI resource lifecycle changes and emits structured events when resources are created, updated, deleted, or change state. You create event rules that match specific event types and route them to actions such as Notifications topics, Functions, or Streaming. This is analogous to AWS EventBridge or Azure Event Grid.

This guide covers both services in depth: creating and managing topics, configuring subscriptions, building event rules with filters, chaining events to Functions for serverless automation, and establishing production-grade event-driven patterns.

Free Tier Allowances

OCI Notifications includes 1,000,000 API requests per month and 1,000 email deliveries per month in the Always Free tier. The Events service has no additional charge beyond the actions it triggers. These generous allowances make it easy to build event-driven automation without cost concerns during development and testing.

Creating and Managing ONS Topics

A topic is a communication channel to which messages are published. Topics are the central entity in the Notifications service. When you publish a message to a topic, it is delivered to all active subscriptions on that topic. Topics are regional resources and belong to a specific compartment.

Topic naming should follow a consistent convention that reflects the purpose and environment. For example, use prefixes like ops- for operational alerts, app-for application events, and sec- for security notifications. This makes it easier to manage topics at scale and apply IAM policies.

bash

# Create a notification topic
oci ons topic create \
  --compartment-id $C \
  --name "ops-alerts" \
  --description "Operational alerts for infrastructure events"

# Create topics for different purposes
oci ons topic create \
  --compartment-id $C \
  --name "security-notifications" \
  --description "Security-related events and policy violations"

oci ons topic create \
  --compartment-id $C \
  --name "cost-alerts" \
  --description "Budget thresholds and cost anomalies"

# List all topics
oci ons topic list \
  --compartment-id $C \
  --query 'data[].{name:name, "topic-id":"topic-id", "lifecycle-state":"lifecycle-state"}' \
  --output table

# Get topic details
oci ons topic get \
  --topic-id <topic-ocid>

Configuring Subscriptions

Subscriptions define how messages published to a topic are delivered. OCI supports multiple subscription protocols, each suited to different use cases:

Email: Sends messages to an email address. The subscriber must confirm the subscription by clicking a link in a confirmation email. Best for human operators and on-call notifications.

HTTPS: Delivers messages as HTTP POST requests to a webhook URL. The endpoint must respond with a 200 status code to acknowledge delivery. Best for integrating with external systems, chat platforms, and custom dashboards.

PagerDuty: Sends events directly to PagerDuty for incident management. Requires a PagerDuty integration key.

Slack: Delivers messages to a Slack channel via an incoming webhook URL. Requires configuring a Slack app with incoming webhooks enabled.

OCI Functions: Invokes an OCI Function with the message payload. This enables serverless processing of events, such as auto-remediation, custom enrichment, or forwarding to external systems.

SMS: Sends text messages to phone numbers. Currently available in limited regions. Useful for critical alerts that require immediate human attention.

bash

# Create an email subscription
oci ons subscription create \
  --compartment-id $C \
  --topic-id <topic-ocid> \
  --protocol "EMAIL" \
  --endpoint "ops-team@example.com"

# Create an HTTPS webhook subscription
oci ons subscription create \
  --compartment-id $C \
  --topic-id <topic-ocid> \
  --protocol "HTTPS" \
  --endpoint "https://hooks.example.com/oci-events"

# Create a Slack subscription
oci ons subscription create \
  --compartment-id $C \
  --topic-id <topic-ocid> \
  --protocol "SLACK" \
  --endpoint "https://hooks.slack.com/services/T00/B00/xxxx"

# Create a PagerDuty subscription
oci ons subscription create \
  --compartment-id $C \
  --topic-id <topic-ocid> \
  --protocol "PAGERDUTY" \
  --endpoint "https://events.pagerduty.com/integration/<key>/enqueue"

# Create a Function subscription
oci ons subscription create \
  --compartment-id $C \
  --topic-id <topic-ocid> \
  --protocol "ORACLE_FUNCTIONS" \
  --endpoint <function-ocid>

# List subscriptions for a topic
oci ons subscription list \
  --compartment-id $C \
  --query 'data[].{protocol:protocol, endpoint:endpoint, "lifecycle-state":"lifecycle-state"}' \
  --output table

# Publish a test message to a topic
oci ons message publish \
  --topic-id <topic-ocid> \
  --title "Test Alert" \
  --body "This is a test notification from OCI ONS"

Confirm Email Subscriptions

Email subscriptions require explicit confirmation before they become active. After creating an email subscription, the subscriber receives a confirmation email with a link that must be clicked within 48 hours. Unconfirmed subscriptions remain in a "Pending" state and do not receive messages. You can resend the confirmation email using the console or API if it was missed or expired.

Events Service: Detecting Resource Changes

The OCI Events service automatically captures resource lifecycle events across your tenancy. Every time a resource is created, updated, deleted, or changes state, an event is emitted with a structured JSON payload containing the resource type, OCID, compartment, event type, and additional details.

Events follow the CloudEvents specification, a CNCF standard for describing event data. Each event includes a source (the OCI service), type (the specific event), subject (the resource OCID), and data (event- specific details). This standardized format makes it easy to process events in a consistent way regardless of the source service.

OCI services that emit events include Compute, Networking, Block Volume, Object Storage, Database, Identity, Functions, and many more. The full list of event types is available in the OCI documentation and can be queried programmatically.

bash

# List available event types (examples)
# com.oraclecloud.computeapi.launchinstance.begin
# com.oraclecloud.computeapi.terminateinstance.begin
# com.oraclecloud.objectstorage.createbucket
# com.oraclecloud.objectstorage.deleteobject
# com.oraclecloud.identity.createpolicy
# com.oraclecloud.databaseservice.autonomous.database.backup.begin

# Example event payload structure:
# {
#   "cloudEventsVersion": "0.1",
#   "eventType": "com.oraclecloud.computeapi.terminateinstance.begin",
#   "source": "ComputeApi",
#   "eventTime": "2026-03-14T10:30:00Z",
#   "contentType": "application/json",
#   "data": {
#     "compartmentId": "ocid1.compartment...",
#     "compartmentName": "production",
#     "resourceId": "ocid1.instance...",
#     "resourceName": "web-server-1",
#     "availabilityDomain": "US-ASHBURN-AD-1"
#   }
# }

Creating Event Rules

Event rules define which events to match and what actions to take when a match occurs. Each rule consists of a condition (filter) that specifies the event types, resource attributes, and optional tag filters, plus one or more actions that execute when the condition is met.

Actions can target Notifications topics (to fan out to multiple subscribers), OCI Functions (for serverless processing), or Streaming (for event buffering and replay). You can have multiple actions per rule, enabling you to simultaneously notify operators and trigger automated remediation.

bash

# Create an event rule for instance termination
oci events rule create \
  --compartment-id $C \
  --display-name "instance-terminated" \
  --is-enabled true \
  --condition '{"eventType": ["com.oraclecloud.computeapi.terminateinstance.begin"], "data": {}}' \
  --actions '{"actions": [{"actionType": "ONS", "topicId": "<topic-ocid>", "isEnabled": true}]}'

# Create a rule for security-sensitive events
oci events rule create \
  --compartment-id $C \
  --display-name "security-policy-changes" \
  --is-enabled true \
  --condition '{"eventType": [
    "com.oraclecloud.identity.createpolicy",
    "com.oraclecloud.identity.updatepolicy",
    "com.oraclecloud.identity.deletepolicy",
    "com.oraclecloud.identity.createuser",
    "com.oraclecloud.identity.deleteuser"
  ], "data": {}}' \
  --actions '{"actions": [
    {"actionType": "ONS", "topicId": "<security-topic-ocid>", "isEnabled": true},
    {"actionType": "FAAS", "functionId": "<audit-function-ocid>", "isEnabled": true}
  ]}'

# Create a rule for Object Storage events in a specific compartment
oci events rule create \
  --compartment-id $C \
  --display-name "bucket-changes" \
  --is-enabled true \
  --condition '{"eventType": [
    "com.oraclecloud.objectstorage.createbucket",
    "com.oraclecloud.objectstorage.deletebucket",
    "com.oraclecloud.objectstorage.updatebucket"
  ], "data": {"compartmentId": "<specific-compartment-ocid>"}}' \
  --actions '{"actions": [{"actionType": "ONS", "topicId": "<topic-ocid>", "isEnabled": true}]}'

# List event rules
oci events rule list \
  --compartment-id $C \
  --query 'data[].{"display-name":"display-name", "lifecycle-state":"lifecycle-state", "is-enabled":"is-enabled"}' \
  --output table

# Get rule details
oci events rule get \
  --rule-id <rule-ocid>

Use Tag-Based Filtering

Event rules support filtering by resource tags, allowing you to create targeted rules that only trigger for specific environments, teams, or projects. For example, you can create a rule that only fires for resources tagged withEnvironment: production by adding a tag filter to the condition. This prevents alert noise from development and test resources.

Event-Driven Automation Patterns

The true power of Events and Notifications comes from combining them with OCI Functions, Streaming, and Connector Hub to build automated operational workflows. Here are the most common patterns used in production OCI environments:

Auto-Remediation: Detect a misconfiguration event (e.g., a security list rule allowing 0.0.0.0/0 on port 22) and trigger a Function that automatically reverts the change. The Function receives the event payload, extracts the resource OCID, and calls the OCI API to update the security list.

Compliance Auditing: Route all IAM and network change events to a Streaming topic for durable storage and replay. A downstream consumer processes the stream and writes audit records to an Autonomous Database for long-term compliance reporting.

Cost Control: Monitor resource creation events and check if the new resource exceeds compartment budget thresholds. If it does, send an alert to the cost management team and optionally tag the resource for review.

ChatOps: Forward critical operational events to Slack or Microsoft Teams via HTTPS webhook subscriptions. Include resource details, links to the OCI Console, and suggested remediation actions in the message payload.

bash

# Example: Function to auto-tag untagged instances
# This Function is triggered by a compute instance launch event
# and adds required tags if they are missing

# Python function example (func.py):
# import io, json, logging
# from fdk import response
# import oci
#
# def handler(ctx, data: io.BytesIO = None):
#     body = json.loads(data.getvalue())
#     instance_id = body["data"]["resourceId"]
#
#     signer = oci.auth.signers.get_resource_principals_signer()
#     compute = oci.core.ComputeClient({}, signer=signer)
#
#     instance = compute.get_instance(instance_id).data
#     tags = instance.freeform_tags or {}
#
#     if "CostCenter" not in tags:
#         tags["CostCenter"] = "unassigned"
#         tags["ReviewRequired"] = "true"
#         compute.update_instance(
#             instance_id,
#             oci.core.models.UpdateInstanceDetails(freeform_tags=tags)
#         )
#
#     return response.Response(ctx, status_code=200,
#         response_data=json.dumps({"tagged": instance_id}))

# Create the event rule for auto-tagging
oci events rule create \
  --compartment-id $C \
  --display-name "auto-tag-new-instances" \
  --is-enabled true \
  --condition '{"eventType": ["com.oraclecloud.computeapi.launchinstance.end"], "data": {}}' \
  --actions '{"actions": [{"actionType": "FAAS", "functionId": "<auto-tag-function-ocid>", "isEnabled": true}]}'

# Create a rule that sends to both notification and function
oci events rule create \
  --compartment-id $C \
  --display-name "public-bucket-alert" \
  --is-enabled true \
  --condition '{"eventType": ["com.oraclecloud.objectstorage.updatebucket"], "data": {}}' \
  --actions '{"actions": [
    {"actionType": "ONS", "topicId": "<security-topic-ocid>", "isEnabled": true},
    {"actionType": "FAAS", "functionId": "<remediation-function-ocid>", "isEnabled": true}
  ]}'

Integration with Connector Hub and Streaming

For more complex event processing pipelines, OCI Connector Hub and Streaming provide additional capabilities beyond direct Events-to-Notifications routing.

Connector Hub moves data between OCI services with configurable transformations. You can use it to route Logging events to Streaming, Object Storage events to Functions, or Monitoring metrics to Notifications. Connector Hub handles batching, retries, and dead-letter queuing automatically.

Streaming (based on Apache Kafka) provides durable, ordered event storage with configurable retention. Events published to a stream can be consumed by multiple consumers independently, replayed from any point in time, and retained for up to 7 days. This decouples event producers from consumers and enables more resilient architectures.

bash

# Create a stream for event buffering
oci streaming admin stream create \
  --compartment-id $C \
  --name "infrastructure-events" \
  --partitions 3 \
  --retention-in-hours 168

# Create an event rule that sends to Streaming
oci events rule create \
  --compartment-id $C \
  --display-name "all-compute-events-to-stream" \
  --is-enabled true \
  --condition '{"eventType": [
    "com.oraclecloud.computeapi.launchinstance.begin",
    "com.oraclecloud.computeapi.launchinstance.end",
    "com.oraclecloud.computeapi.terminateinstance.begin",
    "com.oraclecloud.computeapi.terminateinstance.end"
  ], "data": {}}' \
  --actions '{"actions": [{"actionType": "OSS", "streamId": "<stream-ocid>", "isEnabled": true}]}'

# Consume events from the stream
oci streaming stream cursor create-cursor \
  --stream-id <stream-ocid> \
  --partition "0" \
  --type TRIM_HORIZON

oci streaming stream message get \
  --stream-id <stream-ocid> \
  --cursor <cursor-value> \
  --limit 10

Production Best Practices

Building reliable event-driven architectures requires careful attention to delivery guarantees, error handling, and operational visibility. Here are the essential best practices for OCI Notifications and Events:

Delivery Guarantees: ONS provides at-least-once delivery, meaning messages may be delivered more than once in rare cases. Design your subscribers and Functions to be idempotent so that processing the same event twice does not cause errors or inconsistencies. Use the event's unique eventId for deduplication.

Error Handling: HTTPS subscriptions retry delivery with exponential backoff if the endpoint returns a non-200 status code. After all retries are exhausted, the message is dropped. For critical notifications, use multiple subscription types (e.g., email + Slack) as redundant delivery channels.

Topic Organization: Create separate topics for different severity levels (critical, warning, informational) and different audiences (operations, security, finance). This allows subscribers to opt into only the notifications they need and prevents alert fatigue.

Event Rule Scoping: Scope event rules to the narrowest compartment possible. A rule in the root compartment matches events from all child compartments, which can generate significant noise. Use compartment-specific rules and tag-based filtering to target only relevant resources.

Monitoring: Monitor the ONS service itself using theoci_ons metric namespace. Key metrics includePublishedMessages, DeliveredMessages, andFailedMessages. Create alarms for delivery failures to detect subscriber issues early.

bash

# Monitor notification delivery metrics
oci monitoring metric-data summarize-metrics-data \
  --compartment-id $C \
  --namespace "oci_ons" \
  --query-text 'DeliveredMessages[1h]{topicId = "<topic-ocid>"}.sum()'

# Monitor failed deliveries
oci monitoring metric-data summarize-metrics-data \
  --compartment-id $C \
  --namespace "oci_ons" \
  --query-text 'FailedMessages[1h]{topicId = "<topic-ocid>"}.sum()'

# Create an alarm for delivery failures
oci monitoring alarm create \
  --compartment-id $C \
  --display-name "ons-delivery-failures" \
  --metric-compartment-id $C \
  --namespace "oci_ons" \
  --query-text 'FailedMessages[5m]{topicId = "<topic-ocid>"}.sum() > 0' \
  --severity "WARNING" \
  --destinations '["<ops-topic-ocid>"]' \
  --is-enabled true \
  --body "ONS message delivery failures detected"

# Delete event rules, subscriptions, and topics (cleanup)
oci events rule delete --rule-id <rule-ocid> --force
oci ons subscription delete --subscription-id <sub-ocid> --force
oci ons topic delete --topic-id <topic-ocid> --force

OCI Monitoring & Alarms Guide OCI Connector Hub Guide OCI Functions Serverless Guide

Key Takeaways

1ONS provides publish-subscribe messaging with email, HTTPS, Slack, PagerDuty, and Functions subscriptions.
2The Events service captures resource lifecycle changes and routes them to automated actions.
3Combining Events with Functions enables auto-remediation workflows for security and compliance.
4Event rules support tag-based filtering to target specific environments or teams.

Frequently Asked Questions

How does OCI Notifications compare to AWS SNS?

OCI Notifications (ONS) is functionally similar to AWS SNS, providing publish-subscribe messaging with multiple subscription types. ONS supports email, HTTPS webhooks, Slack, PagerDuty, Functions, and SMS. Key differences include built-in Slack integration (AWS requires Lambda), PagerDuty native support, and 1 million free API requests per month.

What OCI services emit events?

Most OCI services emit events including Compute (instance launch/terminate), Networking (VCN/subnet changes), Identity (user/policy changes), Object Storage (bucket/object operations), Database (backup/scaling), Functions (invocations), and Block Volume (attach/detach). Each event includes the resource OCID, compartment, event type, and operation-specific details.

Written by CloudToolStack Team

Cloud engineers and architects with hands-on experience across AWS, Azure, and GCP. We write guides based on real-world production patterns, not just documentation rewrites.

Disclaimer: This guide is for educational purposes. Cloud services change frequently; always refer to official documentation for the latest information. AWS, Azure, and GCP are trademarks of their respective owners.