Managing Topics and Subscriptions
This section describes how to manage topics and their subscriptions .
A topic is a communication channel for sending messages to its subscriptions. A topic can have zero, one, or multiple subscriptions that are notified whenever a message is published to a topic.
Prerequisites
IAM policies: To use Notifications, you must be given the required type of
access in a policy written by an administrator, whether
you're using the Console or the REST API with an SDK,
CLI, or other tool. For Functions, you must have
FN_INVOKE
permission against the function to be able to add the
function as a subscription to a topic. To authorize your function for access to other Oracle Cloud Infrastructure resources, such as compute instances, include the function in a dynamic group and create a policy to grant the dynamic group access to those resources. For more information, see Accessing Other Oracle Cloud Infrastructure Resources from Running Functions.
If you get a response that you don’t have permission or are unauthorized, check with your administrator. You may not have the required type of access in the current compartment . For more information on user authorizations, see Authentication and Authorization.
Creating Automation with Functions and Events
You can create automation by publishing messages to function subscriptions. For an example of a function subscription, see Scenario A: Automatically Resize VMs.
You can create also automation based on state changes of your topics and subscriptions (Notifications resources) by using event types, rules, and actions. For more information, see Overview of Events.
Using the Console
- Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.
-
Choose a compartment you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.
- Click Topics.
- Click Create Topic at the top of the topic list.
-
In the Create Topic panel, configure your topic.
- Name: Required. Specify a friendly name for the topic. It must be unique across the tenancy; validation is case-sensitive. Avoid entering confidential information.
- Description: Optional. Enter a description for the topic. Avoid entering confidential information.
- Click Create.
- Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.
- Click Topics.
- For the topic you want to delete, click the Actions menu, and then click Delete.
- Confirm when prompted.
- Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.
- Click Topics.
- Click the name of the topic you want to update.
- On the topic detail page, next to Description, click
.
- Edit the description.
- Click
.
Associated subscriptions remain in their current compartments. For more information, see Moving Topics and Subscriptions 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.
- Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.
-
Choose a compartment you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.
- Click Topics.
- Find the topic in the list, click the Actions menu, and then click Move Resource.
- Choose the destination compartment from the list.
- Click Move Resource.
While new subscriptions must be created in the same compartment as the topic, you can move them to different compartments after creating them.
- Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.
- Choose a compartment you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.
- Click Topics.
- Click the name of the topic that you want to add the subscription to.
- On the topic detail page, click Create Subscription.
-
In the Create Subscription panel, configure your subscription for the protocol you want:
Email subscriptionSends 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 service connector messages.Some message types allow friendly formatting.
- Protocol: Select Email.
- Email: Type an email address.
Function subscriptionRuns 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.Note
You must have
FN_INVOCATION
permission against the function to be able to add the function as a subscription to a topic.The Notifications service has no information about a function after it's invoked. For more details, see the troubleshooting information at Function not invoked or run.
Confirmation is not required for function subscriptions.
- Protocol: Select Function.
- Function Compartment: Select the compartment containing your function.
- Function Application: Select the application containing your function.
- Function: Select your function.
HTTPS (Custom URL) subscriptionSends specified information when you publish a message to the subscription's parent topic .
Endpoint format (URL using HTTPS protocol):
https://<anyvalidURL>
Authentication: Only Basic Access Authentication is supported. For more information, see RFC-2617. You can specify a username and password in the URL, as in
https://user:password@domain.com
orhttps://user@domain.com
.Certificates: Only valid certificate authority (CA) certificates are trusted. No self-signed certificates are allowed.
Encryption: As with any subscription protocol, data in the endpoint (including username and password if supplied in the URL) is encrypted in transit over the SSL connection established when using HTTPS, and at rest in the service database.
POST calls: The endpoint that you provide must accept POST calls. The Notifications service uses POST calls to send messages to HTTPS (custom URL) endpoints.
Not supported: Query parameters are not allowed in URLs. Custom HTTP header parameters are not supported. When sending a message to the URL endpoint, the Notifications service adds standard metadata to the HTTP request in the header.
- Protocol: Select HTTPS (Custom URL).
- URL: Type (or copy and paste) the URL you want to use as the endpoint.
PagerDuty subscriptionCreates a PagerDuty incident by default when you publish a message to the subscription's parent topic .Endpoint format (URL):
https://events.pagerduty.com/integration/<integrationkey>/enqueue
Query parameters are not allowed in URLs.To create an endpoint for a PagerDuty subscription (set up and retrieve an integration key), see To create a PagerDuty endpoint
-
Protocol: Select PagerDuty.
URL:
Type (or copy and paste) the integration key portion of the URL for your PagerDuty subscription. (The other portions of the URL are hard-coded.)
Slack subscriptionSends a message to the specified Slack channel by default when you publish a message to the subscription's parent topic .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.Endpoint format (URL):
https://hooks.slack.com/services/<webhook-token>
The <webhook-token> portion of the URL contains two slashes (/).
Query parameters are not allowed in URLs.To create an endpoint for a Slack subscription (using a webhook for your Slack channel), see the Slack documentation.
- Protocol: Select Slack.
- URL: Type (or copy and paste) the Slack endpoint, including your webhook token.
SMS subscriptionSends 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: 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 RegionsYou 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 - Protocol: Select SMS.
- Country: Select the country for the phone number.
- Phone Number: Enter the phone number, using E.164 format.
Example SMS endpoints:
- Phone Number (E.164 format):
+14255550100
- Phone Number (E.164 format):
-
Click Create.
The subscription has been created.
Subscriptions using protocols that require confirmation, such as Email, remain in "Pending" status until confirmation is received. For these subscriptions, a subscription confirmation URL is sent. For detailed steps, see To confirm a subscription.
To view the details of a subscription
To complete this procedure, you must have access to Notifications and permissions to list subscriptions. See IAM Policies (Securing Notifications).
Confirmation is not required for function subscriptions.
Navigate to the confirmation URL that is sent to the subscription's endpoint and follow the provided instructions.
Some protocols provide confirmation URLs in unique ways:
- HTTPS (Custom URL): You can find the confirmation URL in the request header or body of the subscription confirmation message (request of content-type: "application/json") that is sent to the endpoint.
-
In the request header, see the value of the
X-OCI-NS-ConfirmationURL
field.Example request header:"X-OCI-NS-SignatureVersion":"1.0" "X-OCI-NS-Signature":"<example-signature>" "X-OCI-NS-SigningCertURL":"<example-url>" "X-OCI-NS-TopicOcid":"ocid.compartment.oc1..<unique_ID>" "X-OCI-NS-Timestamp":"2019-04-19T21:26:00.310+0000" "X-OCI-NS-MessageId":"<unique_ID>" "X-OCI-NS-TopicName":"mytopic" "X-OCI-NS-MessageType":"SubscriptionConfirmation" "X-OCI-NS-ConfirmationURL":"<exampleConfirmationURL>" "X-OCI-NS-SubscriptionId":"ocid1.onssubscription.oc1.phx.<unique_ID>" "X-OCI-NS-State":"Pending"
See also Standard header metadata.
-
In the request body, see the value of the
ConfirmationURL
key.Example ConfirmationURL key and value (request body):
"ConfirmationURL":"<exampleConfirmationURL>"
-
- PagerDuty: Incident titled "Oracle Notification Service Subscription Confirmation".
- Slack: Message sent to Slack channel containing the text "To confirm the subscription".
- SMS: Message sent to phone number containing the
text "REPLY 'CONFIRM <short-topic-id>' to confirm
subscription."
<short-topic-id> is the short code of the topic that the SMS subscription was added to. The short code is used to identify the topic in messages sent to SMS subscriptions. Each short code contains six case-insensitive alphanumeric characters.
The ability to resend subscription confirmations is only applicable for pending subscriptions.
- Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.
-
Choose a compartment you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.
- Click Subscriptions.
- For the subscription you want to resend the confirmation for, click the Actions menu, and then click Resend Confirmation.
The retry duration is part of the delivery policy for the subscription. By default, Notifications retries delivery of a message for up to two hours.
- Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.
-
Choose a compartment you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.
- Click Subscriptions.
-
For the subscription you want to update, click the Actions menu, and then click Update Delivery Policy.
- In the Update Delivery Policy dialog box, click
for Max Retry Duration in Minutes, type the new value, and then click
.
The associated topic remains in its current compartment. For more information, see Moving Topics and Subscriptions 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.
- Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.
-
Choose a compartment you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.
- Click Subscriptions.
- Find the subscription in the list, click the Actions menu, and then click Move Resource.
- Choose the destination compartment from the list.
- Click Move Resource.
Every message sent out as email contains a link to unsubscribe from the related topic.
- Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.
-
Choose a compartment you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.
- Click Subscriptions.
- For the subscription you want to delete, click the Actions menu, and then click Delete.
- Confirm when prompted.
Managing Tags for a Topic or Subscription
You can apply tags to your resources, such as topics and subscriptions, to help you organize them according to your business needs. You can apply tags at the time you create a topic or subscription, or you can update the topic or subscription later with the tags you want. For general information about applying tags, see Resource Tags.
- Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.
- Choose the Compartment that contains the topic you want to tag, and then click the topic's name.
- Click the Tags tab to view or edit existing tags, or click Add Tags to add new ones.
For more information, see Resource Tags.
- Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.
- Choose the Compartment that contains the subscription you want to tag, and then click the name of the topic that has the subscription.
-
For the subscription you want to tag, click the Actions menu, and then click Add Tags.
To view or edit existing tags, click the Actions menu, and then click View Tags.
For more information, see Resource Tags.
Using the API
For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.
Use these API operations to manage topics:
Use these API operations to manage subscriptions: