Endpoint providers can instruct UBX to alert them when UBX users add or modify
subscriptions for events that an endpoint provides or receives. You make such an instruction as an
API call to UBX.

For example, UBX can notify you when users add a new event subscription to an endpoint. UBX can
also send a notification when a user disables all event subscriptions for the endpoint.

Monitoring event subscription changes can help you to manage system resources because you need to
send event notifications to UBX only for events that are actually requested by UBX users.
Subscription monitoring has the additional benefit of indicating which events are the most or least
popular among UBX users.

UBX can monitor event subscription and notify you automatically when it detects a change in syndication status. UBX sends the notification to a URL that you specify. Notification of syndication changes proceeds as follows:

  • The endpoint provider makes an API call to UBX to request syndication change notifications. You must specify the authentication key for the endpoint and a URL to accept the notifications.
  • UBX begins to monitor event subscriptions for the specified endpoint.
  • UBX user changes an event subscription.
  • UBX detects the change and makes a HTTP call to the specified URL. The call contains a description of the change in a JSON string.

To start monitoring subscriptions for an endpoint, you must register the notification by
calling the UBX v1/subscription/notification API.

Subscription notifications are created for specific endpoints that are registered within a
specific UBX user account. When you start a subscription notification, you are starting
notifications for a specific endpoint and UBX user account. You must submit the authentication key
that was provided by the UBX user account to register the endpoint with UBX.

Following the successful API call, UBX begins sending notifications in response to event
subscription changes.

You can register one syndication change notification for an endpoint. Subsequent registration
calls overwrite an existing registration.

If your endpoint requires an authenticated connection to receive the subscription notifications,
you must specify how UBX must provide the required credentials when it reports a subscription
change. UBX supports several authentication methods.

  • API Key: You specify a key value when you register for subscription
    notification. When UBX reports a subscription change in an HTTP call, UBX adds the specified key in
    the HTTP header. For example, Authorization : Bearer <API key>
  • HTTP Basic: You specify a username and password when you register for
    subscription notification. When UBX reports a subscription change, UBX submits the credentials
    encoded in the HTTP header in RFC 2617 format. For example, Authorization : Basic
    <encoded user ID and password>
  • OAuth: You specify a client ID and client secret when you register for
    subscription notification. When UBX reports a subscription change, UBX includes these values in the
    OAuth parameters that it adds to the header of the HTTP call.
  • OAuth with a refresh token only: You specify a client ID and client secret
    during account provisioning, separately from registration for subscription notification. When UBX
    reports a subscription change, UBX includes a refresh token, but not the client ID or client secret,
    in the OAuth authorization parameters in the HTTP header.

To start subscription change notifications:

  1. In the request header, include the endpoint authentication key as the authorization bearer.
  2. Set the content type to application/json.
  3. Specify the notification request details as the JSON payload in the HTTP request body.

Example

Call PUT https://api-01.ubx.ibmmarketingcloud.com/v1/subscription/notification

Notification format

UBX sends subscription notifications in an HTTP call to the notification URL. Details of the subscription change are provided as a JSON payload.

{ 
   "notificationKey" : "",
   "changeTime" : "",
   "changedSubscriptions" :
   [
      {
      "changeType" : "",
      "eventTypeCode" : "",
      "eventName" : ""
      }
   ]
}

Notification key

The notification key that you specify during registration displays here in each subscription
notification.

Property Use Type Value Description
notificationKey Optional String User-defined UBX includes the value with each notification.

Time of the subscription change

UBX indicates when the subscription change occurred.

Property Use Type Value Description
changeTime Required ISO-8601 System-defined UBX indicates when the subscription change was received.

Description of the subscription change

The description includes the type of subscription change, the UBX event code, and the name of the
event.

Property Use Type Value Description
changeType Required String

Add

Delete

Enable

Disable

Users make these changes in the UBX user interface.
eventTypeCode Required String As defined The event code as defined as an IBM recognized event or as registered with IBM as a custom
event.
eventName Required String As defined Name of the event, as registered with IBM.

To stop subscription change notifications:

To remove a registered subscription notification, you must call DELETE /v1/subscription/notification. Subscription notifications are created for specific endpoints that are registered within a specific UBX user account. When you stop a subscription notification you are stopping notifications for a specific endpoint and UBX user account. You must submit the authentication key that was provided by the UBX user account to register the endpoint with UBX.

  1. In the request header, include the endpoint authentication key as the authorization bearer.
  2. Set the content type to application/json.
  3. Leave the HTTP request body empty.

Example

Call DELETE https://api-01.ubx.ibmmarketingcloud.com/v1/subscription/notification

Join The Discussion

Your email address will not be published. Required fields are marked *