To start monitoring subscriptions for an endpoint, you must register the notification by calling the Acoustic Exchange v1/subscription/notification API.
Subscription notifications are created for specific endpoints that are registered within a specific Acoustic Exchange user account. When you start a subscription notification, you are starting notifications for a specific endpoint and Acoustic Exchange user account. You must submit the authentication key that was provided by the Acoustic Exchange user account to register the endpoint with Acoustic Exchange.
Following the successful API call, Acoustic 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 Acoustic Exchange must provide the required credentials when it reports a subscription change. Acoustic Exchange supports several authentication methods.
- API Key: You specify a key value when you register for subscription notification. When Acoustic Exchange reports a subscription change in an HTTP call, Acoustic Exchange 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 Acoustic Exchange reports a subscription change, Acoustic Exchange 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 Acoustic Exchange reports a subscription change, Acoustic 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 Acoustic Exchange reports a subscription change, Acoustic Exchange includes a refresh token, but not the client ID or client secret, in the OAuth authorization parameters in the HTTP header.
Procedure
- Call PUT https://api-exchange-us-1.goacoustic.com/v1/subscription/notification.
- In the request header, include the endpoint authentication key as the authorization bearer.
- Set the content type to application/json.
- Specify the notification request details as the JSON payload in the HTTP request body.
For details about how to make this call, see PUT /v1/subscription/notification.
Remove a subscription change notification
- Call DELETE https://api-exchange-us-1.goacoustic.com/v1/subscription/notification.
- In the request header, include the endpoint authentication key as the authorization bearer.
- Set the content type to application/json.
- Leave the HTTP request body empty.
Subscription notifications are created for specific endpoints that are registered within a specific Acoustic Exchange user account. When you stop a subscription notification you are stopping notifications for a specific endpoint and Acoustic Exchange user account. You must submit the authentication key that was provided by the Acoustic Exchange user account to register the endpoint with Acoustic Exchange.