Subscription change notification

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

For example, Exchange can notify you when users add a new event subscription to an endpoint. Exchange 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 Exchange only for events that are actually requested by Exchange users. Subscription monitoring has the additional benefit of indicating which events are the most or least popular among Exchange users.

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

  • The endpoint provider makes an API call to Acoustic Exchange to request syndication change notifications. You must specify the authentication key for the endpoint and a URL to accept the notifications.
  • Exchange begins to monitor event subscriptions for the specified endpoint.
  • Exchange user changes an event subscription.
  • Exchange 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 Exchange v1/subscription/notification API.

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

Following the successful API call, Exchange 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 Exchange must provide the required credentials when it reports a subscription change. Exchange supports several authentication methods.

API Key: You specify a key value when you register for subscription notification. When Exchange reports a subscription change in an HTTP call, Exchange adds the specified key in the HTTP header. For example, Authorization : Bearer
HTTP Basic: You specify a username and password when you register for subscription notification. When Exchange reports a subscription change, Exchange submits the credentials encoded in the HTTP header in RFC 2617 format. For example, Authorization : Basic
OAuth: You specify a client ID and client secret when you register for subscription notification. When Exchange reports a subscription change, Exchange 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 Exchange reports a subscription change, Exchange 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-exchange-us-1.goacoustic.com/v1/subscription/notification

Notification format

Exchange 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

Acoustic Exchange includes the value with each notification.

Time of the subscription change

Exchange indicates when the subscription change occurred.

Property

Use

Type

Value

Description

changeTime

Required

ISO-8601

System-defined

Acoustic Exchange indicates when the subscription change was received.

Description of the subscription change

The description includes the type of subscription change, the Exchange 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 Acoustic Exchange UI.

eventTypeCode

Required

String

As defined

The event code as defined as an Acoustic Exchange recognized event or as registered with Exchange as a custom event.

eventName

Required

String

As defined

Name of the event, as registered with Acoustic Exchange.

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 Exchange user account. When you stop a subscription notification you are stopping notifications for a specific endpoint and Exchange user account. You must submit the authentication key that was provided by the Exchange user account to register the endpoint with Exchange.

  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-exchange-us-1.goacoustic.com/v1/subscription/notification