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.comorhttps://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"} -vIf 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 headerresponse. When your endpoint receives an unauthenticated request, it should return that response with aWWW-Authenticateheader. The header value should contain the keywordBasicand 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 list page, specifying the topic in the panel: Select Create Subscription, and then select a Subscription Topic. 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 to a Different Compartment.