Skip to content

Subscription

Individual subscription. It's a unique combination of:

  • Address,
  • Subscription method,
  • Hub.

Events created on a Hub Page depending on configuration will be sent to subscriptions of that Hub.
Subscription can be created for only a subset of Hub services which will result in not receiving notifications about events affecting services that were not selected.

In order to create or manage multiple subscriptions that should be associated with the same person or entity, it's recommended to use Subscriber and Subscriber Subscription endpoints.

Operations

Create a Subscription

Request

Creates a new Subscription. Creates Subscriber record as well.
Besides regular validation - like address correctness - there are a few additional constraints:

  • Address has to be unique for current Hub,
  • Single Subscriber can't have multiple subscriptions with same method name. For example it's not allowed for one Subscriber to have for example two email subscriptions.
Security
ApiKeyAuth
Path
subdomainstringrequired

Unique subdomain of requested Hub.

Query
api_versionstring

Api version

Value:"V3-R1"
Bodyapplication/json
addressstringrequired

Address for a subscription. Exact meaning depends on method name:

  • email - email address,
  • sms - phone number,
  • webhook - URL,
  • slack - Slack Incoming Webhook URL,
  • teams - MS Teams Incoming Webhook URL.
Example:"example@statushub.com"
method_namestringrequired
Enum:"email""sms""webhook""slack""teams"
Example:"email"
services_selectionobjectrequired

"all" has precedence over "services". If "all" is false, "services" can't be empty. If "all" is true, "services" value is being ignored

configurationobject

Additional configuration for this method name or this Subscription

Example:
{
  "content_type": "application/json"
}
labelstring or null

Additional information to add better meaning for subscription.
Typically used to add responsible person name or team to SMS or URL-based subscriptions where address alone is not enough to know who is receiving the notifications.
Not available for email subscriptions.

Example:"Responsible person name"
less_verboseboolean

Subscription will receive the minimum number of notifications per incident - typically first and final.

Default:false
Example:true
protectedboolean

Subscription is protected which means it doesn't have the ability of self-service like editing the services list or subscription options as well as doesn't have the ability to self-unsubscribe.
Typically used for group email subscriptions where without this option, any member of an email group could use unsubscribe through the unsubscribe link sent in every notification. And as a result the whole group would stop receiving notifications.

Default:false
Example:false
subscriber_idinteger

id of the Subscriber. If not provided, StatusHub will create new, empty Subscriber record.

Example:9

Minimal example creating email subscription.

curl -i -X POST \
  'https://subdomain-of-your-account.app.statushub.io/api/v3/hubs/{subdomain}/subscriptions?api_version=V3-R1' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "address": "example@statushub.com",
    "method_name": "email",
    "services_selection": {
      "all": true
    }
  }'

Responses

OK

Bodyapplication/json
idinteger, >= 1
Example:86
addressstring

Address for a subscription. Exact meaning depends on method name:

  • email - email address,
  • sms - phone number,
  • webhook - URL,
  • slack - Slack Incoming Webhook URL,
  • teams - MS Teams Incoming Webhook URL.
Example:"example@statushub.com"
configurationobject

Additional configuration for this method name or this Subscription

Example:
{
  "content_type": "application/json"
}
method_namestring
Enum:"email""sms""webhook""slack""teams"
Example:"email"
subscriber_idinteger, >= 1
Example:87
services_selectionobject
flagsBasic flags (object) or Extended flags (object)
One of:
labelstring or null

Additional information to add better meaning for subscription.
Typically used to add responsible person name or team to SMS or URL-based subscriptions where address alone is not enough to know who is receiving the notifications.
Not available for email subscriptions.

Example:"Responsible person name"
created_atstring, (date-time)

Timestamp of record creation.
ISO8601 formatted time (UTC).

Example:"2020-09-01T08:29:00Z"
updated_atstring, (date-time)

Timestamp of last modification of record.
ISO8601 formatted time (UTC).

Example:"2020-09-01T08:29:00Z"
Response
{
  "id": 86,
  "address": "example@statushub.com",
  "configuration": {
    "content_type": "application/json"
  },
  "method_name": "email",
  "subscriber_id": 87,
  "services_selection": {
    "all": true,
    "services": [ … ]
  },
  "flags": {
    "deleted": false
  },
  "label": "Responsible person name",
  "created_at": "2020-09-01T08:29:00Z",
  "updated_at": "2020-09-01T08:29:00Z"
}