Overview of Notifications
Use the Oracle Cloud Infrastructure Notifications service to set up communication channels for publishing messages using topics and subscriptions.
The Notifications service lets you know when something happens with your resources in Oracle Cloud Infrastructure. Using alarms, event rules, and connectors, you can get human-readable messages through supported endpoints, including email and text messages (SMS). You can also automate tasks through custom HTTPS endpoints and Oracle Cloud Infrastructure Functions. You can also directly publish messages.
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.
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.
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.
- Immediate retry.
- Exponential backoff retry for the period of the subscription's retry duration, using the following timing:
- 1 minute
- 2 minutes
- 4 minutes
- 8 minutes
- 16 minutes
- 32 minutes
- Discarding of the message at the end of the retry duration.
To change a subscription's retry duration, see Updating the Delivery Policy for a Subscription.
Notifications Concepts
The following concepts are essential to working with Notifications.
- friendly formatting
- A setting to increase human readability of messages.
- 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.
- subscription
- An endpoint for a topic. Published messages are sent to each subscription for a topic.
- topic
- 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 and Delivery
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.
Creating Automation with Functions and Events
You can create automation by publishing messages to topics that include function subscriptions. For an example of a function subscription, see Scenario A: Automatically Resizing VMs.
You can create also automation based on state changes of topics and subscriptions (Notifications resources) by using event types, rules, and actions.
Availability
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 |
Yes |
Supports special handling for failed email delivery. | No |
Yes |
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.
Ways to Access Notifications
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.
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, and so on. 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 resources, see IAM Policies (on the Securing Notifications page).
Limits on Notifications
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.
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 |
Security
Learn about security for Notifications.
Grant access to topics and subscriptions. See Securing Notifications.