Overview of Notifications

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.

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.

To change a subscription's retry duration, see Updating the Delivery Policy for a Subscription.

The following concepts are essential to working with Notifications.

friendly formatting

A setting to increase human readability of messages.

Supported subscription protocols:

• Email

Supported message types:

• Alarm messages (when Notifications is the destination)

  See alarm message examples and Updating an Alarm After Moving a Resource.

• Connector messages (when Notifications is the target service)

  See connector message examples and Updating a Connector to Use Friendly Formats.

message

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.

notification

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:

• Contextual notification: Created from a quick start template or focused options that are relevant to the given resource.

  For instructions with a compute instance, see Setting Up Contextual Notifications for an Instance.

• Traditional notification: Created from a supported integration point.

  Example scenarios for traditional notifications include automatically resizing VMs, sending alarm messages to Slack and SMS, and filing Jira tickets for reminders.

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.

subscription

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 .

  Note
  
  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 connector messages.

  Some message types use 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 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.

  Note
  
  

  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: Announcements, Monitoring, and Connector Hub. SMS messages sent by unsupported services are dropped. See Cause: Unsupported resource used for SMS.

  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 SMS alarm messages and SMS 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

topic

A communication channel for sending messages to subscriptions. Each topic name is unique across the tenancy.

Resources publish messages to the configured topic . Notifications then delivers messages to active subscriptions  in the topic.

Resources that can send messages include alarms, announcement subscriptions, event rules, connectors, and contextual notifications (alarms and event rules). (A user, service, or app can also send a message through direct publication.)

For example, consider an alarm configured to send messages to a topic. This topic contains email, Slack, and SMS subscriptions. When the alarm trigger rule is breached, the alarm publishes a message to the topic. Notifications then delivers the message to the topic's active subscriptions. In this example, the Slack subscription is pending because it hasn't been confirmed yet. Notifications delivers the message to the email and SMS subscriptions only, because these are the only active subscriptions in the topic.

For metrics that track published and delivered messages, see Available Metrics: oci_notification.

Alarms

When an alarm's  trigger rule is breached, the alarm sends an alarm message to the configured topic . Notifications then delivers the message to active subscriptions  in that topic. See Managing Alarms.

A contextual notification can include an alarm.

Announcement Subscriptions

An announcement subscription sends console announcement messages to the configured topic . Notifications then delivers the message to active subscriptions  in that topic.

Event Rules

When triggered, an event rule sends an event message to the configured topic . Notifications then delivers the message to active subscriptions  in that topic. See Managing Rules for Events.

A contextual notification can include an event rule.

Connectors

A connector  sends a connector message to the configured topic . Notifications then delivers the message to active subscriptions  in that topic. See Managing Connectors.

Direct Publication

A user (or a service or app) sends a message  to the configured topic . Notifications then delivers the message to active subscriptions  in that topic. See Publishing a Message to a Topic.

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.

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.

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.

You can access the Notifications service using the Console or the Notifications REST API. Instructions for the Console, CLI, and API are included 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.

Administrators: For common policies that give groups access to Notifications resources, see IAM Policies (on the Securing Notifications page).

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