Developer API Reference

Subscribing to Location Alerts

A client can choose to receive notifications when an alert becomes active for a StreamLabs® Location and when it ends.

Step 1: Create a Subscription

GET /v1/locations/{locationId}/subscriptions

Body Parameters

endpoint string required
A Fully Qualified Domain Url https endpoint that will receive alerts for this location. The endpoint should successfully respond to GET and POST requests and should respond with valid json

Response Body

A successful request returns the HTTP 200 OK status code and a JSON response body with the status as pending

subscriptionId string
subscription identifier
locationId string
location identifier
endpoint string
A secured Fully Qualified Domain Url endpoint that receives location alerts
status string
status of the subscription
POST /v1/locations/{locationId}/subscriptions HTTP/1.1
Content-Type: application/json
Authorization: Bearer {}

{"endpoint": "https://exampleurl.com"}
{
  "subscriptionId": "3bb2255b...2a48",
  "locationId": "be926a02...dbc9",
  "endpoint": "https://exampleurl.com",
  "status": "pending"
}

Step 2: Recieve your confirmation token

The endpoint provided should also receive a POST request with a confirmationUrl and confirmationToken in the body.

POST {endpoint}

Body Parameters

confirmationUrl string
A Fully Qualified Domain Url https with the confirmation token as a query parameter
confirmationToken string
A short-lived token
POST {endpoint} HTTP/1.1
Content-Type: application/json

{
  "confirmationUrl": "https://api.streamlabswater.com/v1/subscriptions/3bb2..7/confirm?confirmationToken=r3vHQ2...",
  "confirmationToken": "r3vHQ2NXpkK..."
}

Step 3: Confirm your Subscription

Make a GET request to the confirm subscription endpoint with the confirmation token as query string parameter

GET /v1/subscriptions/{subscriptionId}/confirm

Query Parameters

confirmationToken string
A short-lived token

A successful request returns the HTTP 200 OK status code and a JSON response body with the status as confirmed

Response Body

subscriptionId string
subscription identifier
locationId string
location identifier
endpoint string
A secured Fully Qualified Domain Url endpoint that receives location alerts
status string
status of the subscription

GET /v1/subscriptions/{subscriptionId}/confirm HTTP/1.1
  ?confirmationToken={confirmationToken}
{
  "subscriptionId": "3bb2255b...2a48",
  "locationId": "be926a02...dbc9",
  "endpoint": "https://exampleurl.com",
  "status": "confirmed"
}