Managing Topics and 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 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.

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.

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 .
5. Edit the description.
6. Click .

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

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.

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:

     • Phone Number (E.164 format): +14255550100

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.

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".
  Example of confirmation incident (at the time this document was published)

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

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.

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

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.

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.

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.

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.