Oracle Cloud Infrastructure Documentation

Creating an HTTPS (Custom URL) Subscription

Create an HTTPS (Custom URL) subscription in Notifications.

Before You Begin

Ensure that the URL endpoint that you plan to use for the subscription meets the following requirements:

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

The endpoint for the HTTPS (Custom URL) subscription must be publicly accessible.

Notifications doesn't support private endpoints for HTTPS (Custom URL) subscriptions. Notifications makes an HTTP POST request to your endpoint through the public internet when you create an HTTPS (Custom URL) subscription in a topic.

To check if your endpoint is publicly accessible, make a sample POST request from your local machine.

Example:

curl -X POST <endpoint> -H "Content-Type:text/plain; charset=UTF-8" --data {"key":"value"} -v

If your endpoint is publicly accessible, then the command returns the following HTTP status code: 

200 OK
Unauthorized header

The client service must be able to support the HTTP/1.1 401 Unauthorized header response. When your endpoint receives an unauthenticated request, it should return that response with a WWW-Authenticate header. The header value should contain the keyword Basic and other optional parameters supported in RFC-2617: HTTP Authentication: Basic and Digest Access Authentication.

Example:

WWW-Authenticate: Basic

Query parameters aren't allowed in URLs. Custom HTTP header parameters aren't supported. When sending a message to the URL endpoint, the Notifications service adds standard metadata to the HTTP request in the header.

  • These steps show how to open the Create Subscription panel from the details page for the topic that you want to add the subscription to. You can also open this panel from the Subscriptions page, specifying the topic in the panel: Click Create Subscription, and then select a Subscription Topic.

    1. Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.
    2. On the Topics page, select the compartment that contains the topic that you want.
    3. Click the name of the topic that you want to add the subscription to.
    4. On the Topic Details page, click Create Subscription.
    5. In the Create Subscription panel, for Protocol, select HTTPS (Custom URL).
    6. Enter the URL that you want to use as the endpoint, using the following format: 
      https://<anyvalidURL>
      Note

      Ensure that the URL meets the requirements provided at the beginning of this help topic. Query parameters aren't permitted in URLs.
    7. Click Create.

    Notifications creates the HTTPS (Custom URL) subscription and sends a confirmation URL to its endpoint. The subscription is pending until confirmation is received.

  • Use the oci ons subscription create command and required parameters to create an HTTPS (Custom URL) subscription:

    oci ons subscription create --protocol "CUSTOM_HTTPS" --subscription-endpoint <URL> [...]

    For a complete list of parameters and values for CLI commands, see the Command Line Reference for Notifications.

  • Run the CreateSubscription operation to create an HTTPS (Custom URL) subscription.

What's Next

To activate the new subscription, navigate to the confirmation URL that was sent to the HTTPS endpoint.

Although a new subscription must be in the same compartment as its parent topic, you can move it to another compartment after creation. See Moving a Subscription.