Notifications Overview

Use the Oracle Cloud Infrastructure Notifications service to set up communication channels for publishing messages using topics and subscriptions.

The Oracle Cloud Infrastructure Notifications service broadcasts messages to distributed components through a publish-subscribe pattern, delivering secure, highly reliable, low latency and durable messages for applications hosted on Oracle Cloud Infrastructure and externally. Use Notifications to get messages whenever alarms, service connectors, and event rules are triggered. You can also directly publish messages.


Watch a video introduction to the service.

How Notifications Works

The Notifications service enables you to set up communication channels for publishing messages using topics  and subscriptions . When a message is published to a topic, the Notifications service sends the message to all of the topic's subscriptions.

Standard header metadata

When delivering messages, Notifications appends the following header metadata.

For all messages:

  • Content-Type
  • X-OCI-NS-MessageId
  • X-OCI-NS-TopicOcid
  • X-OCI-NS-TopicName
  • X-OCI-NS-MessageType
  • X-OCI-NS-UnsubscribeURL

For confirmation messages:

  • X-OCI-NS-ConfirmationURL
  • X-OCI-NS-SubscriptionId

For message signature validation:

  • X-OCI-NS-Signature
  • X-OCI-NS-Timestamp
  • X-OCI-NS-SignatureVersion
  • X-OCI-NS-SigningCertURL

When a subscriber’s endpoint does not acknowledge receipt of the message, the Notifications service retries delivery. This situation can occur when the endpoint is offline. For example, the email server for an email address may be down.

Delivery retry details

Notifications retries delivery following these steps until either (a) acknowledgement is received or (b) the subscription's retry duration is over. By default, the retry duration is two hours.

  1. Immediate retry.
  2. Exponential backoff retry for the period of the subscription's retry duration, using the following timing:
    1. 1 minute
    2. 2 minutes
    3. 4 minutes
    4. 8 minutes
    5. 16 minutes
    6. 32 minutes
  3. Discarding of the message at the end of the retry duration.

You can change the retry duration for a subscription. For instructions using the Console, see To update the retry duration for a subscription. For the API, use the following operation: UpdateSubscription.

Notifications Concepts

The following concepts are essential to working with Notifications.

The content that is published to a topic. Each message is delivered at least once per subscription. Every message sent out as email contains a link to unsubscribe from the related topic.

Friendly formatting: Select friendly formatting to increase human readability of messages.

Supported subscription protocols:

Supported message types:

A configuration for sending messages, such as an alarm or event rule. Each message is sent to subscriptions in the specified topic.
The following types of notifications are available:
After creating the notification, you can manage it as usual. For example, if the notification is an alarm, manage it using the Alarms page in the Console.
An endpoint for a topic. Published messages are sent to each subscription for a topic.
Supported subscription protocols:
  • Email:

    Sends an email message when you publish a message  to the subscription's parent topic .


    Follow best practices for integrating with Email Delivery. See Maintain a Positive Email Sender Reputation and Set Up Custom Domains for Email.
    Message contents and appearance vary by message type. See alarm messages, event messages, and service connector messages.

    Some message types allow friendly formatting.

  • Function:
    Runs the specified function when you publish a message  to the subscription's parent topic . For example, runs a function to resize VMs when an associated alarm is triggered.
  • HTTPS (Custom URL):

    Sends specified information when you publish a message  to the subscription's parent topic .

  • PagerDuty:
    Creates a PagerDuty incident by default when you publish a message  to the subscription's parent topic .
  • Slack:
    Sends a message to the specified Slack channel by default when you publish a message  to the subscription's parent topic .
    Message contents and appearance vary by message type. See alarm messages, event messages, and service connector messages.
  • SMS:
    Sends a text message using Short Message Service (SMS) to the specified phone number when you publish a message  to the subscription's parent topic . Supported endpoint formats: E.164 format.

    International SMS capabilities are required if SMS messages come from a phone number in another country. We continuously add support for more countries so that more users can receive SMS messages from local phone numbers.

    SMS subscriptions are enabled only for messages sent by the following Oracle Cloud Infrastructure services: Monitoring, Service Connector Hub. SMS messages sent by unsupported services are dropped. Troubleshoot dropped messages.

    The Notifications service delivers SMS messages from a preconfigured pool of numbers. You might receive SMS messages from multiple numbers.

    Message contents and appearance vary by message type. See alarm messages, event messages, and service connector messages.
    Available Countries and Regions

    You can use Notifications to send SMS messages to the following countries and regions:

    Country or region ISO code
    Australia AU
    Brazil BR
    Canada CA
    Chile CL
    China CN
    Costa Rica CR
    Croatia HR
    Czechia CZ
    France FR
    Germany DE
    Hungary HU
    India IN
    Ireland IE
    Israel IL
    Japan JP
    Lithuania LT
    Mexico MX
    Netherlands NL
    New Zealand NZ
    Norway NO
    Philippines PH
    Poland PL
    Portugal PT
    Romania RO
    Saudi Arabia SA
    Singapore SG
    South Africa ZA
    South Korea KR
    Spain ES
    Sweden SE
    Switzerland CH
    Ukraine UA
    United Arab Emirates AE
    United Kingdom GB
    United States US
A communication channel for sending messages to subscriptions. Each topic name is unique across the tenancy.

Messages sent out as email by the Oracle Cloud Infrastructure Notifications service are processed and delivered through Oracle resources in U.S.-based regions.

Flow of Message Publication

Notifications publishes messages when event rules are triggered, alarms are breached, service connectors run, or someone directly publishes a message.

Event rules

Notifications sends event messages when rules are triggered. The event message is sent to the topic  specified in the rule. For example, a message might be configured for new databases. See Managing Rules for Events.

This image shows Notifications in the context of event rules.


Notifications sends alarm messages when alarms  are breached. The alarm message is sent to the topic  specified in the alarm. For example, an alarm message might be configured for high CPU usage. See Managing Alarms.

This image shows Notifications in the context of alarms.

Service connectors

Notifications sends service connector messages when service connectors  are running. The service connector message is sent to the topic  specified in the service connector. For example, a service connector might be configured to send usage logs. See Managing Service Connectors.

This image shows Notifications in the context of service connectors.

Direct publication

Notifications sends messages  when you (or a service or app) publish the messages directly. The message is sent to the topic  you specify. See Publishing Messages.

This image shows Notifications as used to directly publish a message.


The Notifications service is available in all Oracle Cloud Infrastructure commercial regions. See About Regions and Availability Domains for the list of available regions, along with associated locations, region identifiers, region keys, and availability domains.

Service Comparison for Sending Email Messages

Consider the following service features when deciding whether to use the Notifications service or the Email Delivery service to send your email messages. For more information about Email Delivery, see Overview of the Email Delivery Service.

Service Feature Notifications service Email Delivery service
Requires confirmation before sending email. Yes No
Allows email decorations, such as signatures. Yes No
Allows raw email messages. No Yes
Supports MIME attachments. No


Supports special handling for failed email delivery. No


Priced for small messages (less than 32 KB, with a 64-KB limit). Yes No
Priced for large messages (greater than 32 KB, with a 2-MB limit). No Yes

Resource Identifiers

Most types of Oracle Cloud Infrastructure resources have a unique, Oracle-assigned identifier called an Oracle Cloud ID (OCID). For information about the OCID format and other ways to identify your resources, see Resource Identifiers.

Moving Topics and Subscriptions to a Different Compartment

You can move topics and subscriptions from one compartment to another. When you move a topic to a new compartment, its associated subscriptions remain in their existing compartment. The same consideration applies when moving a subscription: its associated topic remains in its existing compartment.

After you move the topic or subscription to the new compartment, inherent policies apply immediately and affect access to the moved topic or subscription through the Console. For more information, see To move a resource to a different compartment.


To move resources between compartments, resource users must have sufficient access permissions on the compartment that the resource is being moved to, as well as the current compartment. For more information about permissions for Notifications resources, see Details for the Notifications Service.

Ways to Access Notifications

You can access the Notifications service using the Console (a browser-based interface) or the Notifications REST API. Instructions for the Console and API are included in topics throughout this guide. For a list of available SDKs, see Software Development Kits and Command Line Interface.

Console: To access Notifications using the Console, you must use a supported browser. To go to the Console sign-in page, open the navigation menu at the top of this page and click Infrastructure Console. You are prompted to enter your cloud tenant, your user name, and your password. Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.

API: To access Notifications through API, use Notifications API.

CLI: See Command Line Reference for Notifications.

Authentication and Authorization

Each service in Oracle Cloud Infrastructure integrates with IAM for authentication and authorization, for all interfaces (the Console, SDK or CLI, and REST API).

An administrator in your organization needs to set up groups , compartments , and policies  that control which users can access which services, which resources, and the type of access. For example, the policies control who can create new users, create and manage the cloud network, launch instances, create buckets, download objects, etc. For more information, see Getting Started with Policies. For specific details about writing policies for each of the different services, see Policy Reference.

If you’re a regular user (not an administrator) who needs to use the Oracle Cloud Infrastructure resources that your company owns, contact your administrator to set up a user ID for you. The administrator can confirm which compartment or compartments you should be using.

Administrators: For common policies that give groups access to Notifications, see Allow a group to manage topics, Allow a group to manage topic subscriptions, and Allow a group to publish messages to topics.

Limits on Notifications

See Service Limits for a list of applicable limits and instructions for requesting a limit increase. To set compartment-specific limits on a resource or resource family, administrators can use compartment quotas.

Limits for publishing messages (PublishMessage operation)

All limits are per tenancy.

Limit type Limit amount
Message size per request 64KB
Message delivery rate per endpoint for HTTP-based protocols (endpoints that begin with "http:" or "https:") 60 messages per minute
Message delivery rate per endpoint for Email protocol 10 messages per minute
Messages per minute (also known as Transactions Per Minute, or TPM) 60 per topic


Learn about security for Notifications.

Grant access to topics and subscriptions. See Securing Notifications.