Oracle Cloud Infrastructure Documentation

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

To create a topic
  1. Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.

  2. 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.

  3. Click Topics.
  4. Click Create Topic at the top of the topic list.

  5. 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.
  6. Click Create.
To delete a topic
  1. Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.
  2. Click Topics.
  3. For the topic you want to delete, click the Actions menu, and then click Delete.
  4. Confirm when prompted.
To update the description for a topic
  1. Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.
  2. Click Topics.
  3. Click the name of the topic you want to update.
  4. On the topic detail page, next to Description, click Edit.
  5. Edit the description.
  6. Click Save.
To move a topic to a different compartment

Associated subscriptions remain in their current compartments. For more information, see Moving Topics and Subscriptions to a Different Compartment.

Note

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.
  1. Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.

  2. 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.

  3. Click Topics.
  4. Find the topic in the list, click the Actions menu, and then click Move Resource.
  5. Choose the destination compartment from the list.
  6. Click Move Resource.
To create a subscription
Note

While new subscriptions must be created in the same compartment as the topic, you can move them to different compartments after creating them.
  1. Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.
  2. 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.
  3. Click Topics.
  4. Click the name of the topic that you want to add the subscription to.
  5. On the topic detail page, click Create Subscription.

  6. In the Create Subscription panel, configure your subscription for the protocol you want: 

    Email subscription

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

    Some message types allow friendly formatting.

    • Protocol: Select Email.
    • Email: Type an email address.
    Function subscription
    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.
    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) subscription

    Sends 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: HTTP Authentication: Basic and Digest Access Authentication. You can specify a username and password in the URL, as in https://user:password@domain.com or https://user@domain.com. In the URL, encode (escape) the characters noted at RFC-3986: Uniform Resource Identifier (URI): Generic Syntax.

    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 subscription
    Creates 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 subscription

    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.
    Sends a message to the specified Slack channel by default when you publish a message  to the subscription's parent topic .

    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 subscription
    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: 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
    • Protocol: Select SMS.
    • Country: Select the country for the phone number.
    • Phone Number: Enter the phone number, using E.164 format.

      Example SMS endpoints:

  7. 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).

  1. Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.
  2. 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.
  3. Click Subscriptions.
    The value in the Protocol column indicates the subscription type. For example, PagerDuty in that column indicates a PagerDuty subscription.
  4. Click the link in the Subscription OCID column for the subscription you want.
    The detail page for the selected subscription is displayed. For a PagerDuty subscription, its endpoint URL is listed.
To confirm a subscription

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.

    Note

    Missing an SMS confirmation message? See International SMS capabilities.
To resend a subscription confirmation

The ability to resend subscription confirmations is only applicable for pending subscriptions.

  1. Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.

  2. 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.

  3. Click Subscriptions.
  4. For the subscription you want to resend the confirmation for, click the Actions menu, and then click Resend Confirmation.
To update the retry duration for a subscription

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.

  1. Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.

  2. 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.

  3. Click Subscriptions.

  4. For the subscription you want to update, click the Actions menu, and then click Update Delivery Policy.

  5. In the Update Delivery Policy dialog box, click Edit for Max Retry Duration in Minutes, type the new value, and then click Save.
To move a subscription to a different compartment

The associated topic remains in its current compartment. For more information, see Moving Topics and Subscriptions to a Different Compartment.

Note

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.
  1. Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.

  2. 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.

  3. Click Subscriptions.
  4. Find the subscription in the list, click the Actions menu, and then click Move Resource.
  5. Choose the destination compartment from the list.
  6. Click Move Resource.
To delete a subscription (unsubscribe)
Note

Every message sent out as email contains a link to unsubscribe from the related topic.
  1. Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.

  2. 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.

  3. Click Subscriptions.
  4. For the subscription you want to delete, click the Actions menu, and then click Delete.
  5. 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.

To manage tags for a topic
  1. Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.
  2. Choose the Compartment that contains the topic you want to tag, and then click the topic's name.
  3. Click the Tags tab to view or edit existing tags, or click Add Tags to add new ones.

For more information, see Resource Tags.

To manage tags for a subscription
  1. Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.
  2. Choose the Compartment that contains the subscription you want to tag, and then click the name of the topic that has the subscription.

  3. 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: