The Notification Pipeline

The notification pipeline is a websocket connection that broadcasts the events of a hub or an account. It broadcasts JSON messages over the socket, with a header field that can be used to determine the event that took place.

Attributes
  • topic
    string

    A header topic, for the full list see the table included on this page.

  • object
    object

    The ID of the notification and potential state and error information.

    Show child fields
  • context
    object

    The context associated with this notification including but not limited to data on the hub, account, environment, DNS zone, cluster, or containers associated with this notification.

    Show child fields

Authenticating

Connecting to the websocket is a two step process.

First you authenticate against one of the two following endpoints:

/v1/channels/account/notifications
/v1/channels/hubs/current/notifications

This returns a URL and a token you can use to create a websocket connection to the notification pipeline.

If you're using the TypeScript client this is automatically handled for you. The function calls are shown in the example area. If you're not using the TypeScript client and want to pass credentials to your websocket client of choice, you can use cURL to authenticate and pass the credentials to your client.

The return from the authentication request will be a token, and the token will need to be appended to the URL as a parameter to complete the websocket connection.

Hub

https://api.cycle.io/v1/channels/hubs/current/notifications?token=5d71fa31db2ab0000167b87e

Account

https://api.cycle.io/v1/channels/hubs/current/notifications?token=5d71fa31db2ab0000167b87e

Connecting to the Notification Pipeline

There are two pipelines you can connect to, Hub and Account. The account pipeline will send information about events happening that relate to account state, new and updated hubs, and account errors, while the hub pipeline will send notifications about all other available events happening on the hub. The notification pipeline will only send meta information. It's at your discretion to use that information and decide whether to make a follow up API call for the rest.

Account and Hub Headers

HeaderTypeDescription
announcement.createdAccountAn announcement has been created.
announcement.updatedAccountAn announcement has been updated.
announcement.state.changedAccountThere has been a change to announcements
account.state.changedAccountThe state of an account has changed.
account.errorAccountAn account error has occurred.
billing.credit.state.changedHubA credit state has changed.
billing.credit.errorHubA credit error has occurred.
billing.discount.state.changedHubA discount items state has changed.
billing.discount.errorHubA discount item error has occurred.
billing.invoice.state.changedHubA billing invoice has changed state.
billing.invoice.errorHubA billing invoice has encountered an error.
billing.invoice.createdHubA new billing invoice was created.
billing.method.state.changedHubThe billing method state has been changed.
billing.method.errorHubA billing method error has occurred.
billing.method.createdHubA billing method has been created.
billing.method.updatedHubThe billing method has been updated.
billing.order.state.changedHubAn order state has changed.
billing.order.errorHubAn order error has occurred.
billing.order.createdHubA new order has been created.
billing.order.updatedHubA billing order has been updated.
billing.service.state.changedHubA billing service state has changed.
billing.service.errorHubA billing service error has occurred.
container.createdHubA container has been created.
container.updatedHubA containers has been updated.
container.reconfiguredHubA container has been reconfigured.
container.state.changedHubA container state has changed.
container.desired_state.changedHubA container state change has been requested.
container.errorHubA container error has occurred.
container.instance.state.changedHubThere has been a state change in the container instance.
container.instance.errorHubThe container instance has produced an error
container.instances.reconfiguredHubThe container instance has been reconfigured.
dns.certificate.state.changedHubA certificate state has changed.
dns.certificate.errorHubA certificate error has occurred.
dns.zone.state.changedHubA DNS zone state change has occurred.
dns.zone.errorHubA DNS zone error has occurred.
dns.zone.createdHubA DNS zone has been created.
dns.zone.verifiedHubA DNS zone has been verified.
dns.zone.reconfiguredHubA DNS zone has been reconfigured.
dns.zone.records.reconfiguredHubThe DNS Zone records have been reconfigured.
dns.zone.record.state.changedHubA DNS Zone record has changed state.
dns.zone.record.certificate.readyHubA DNS Zone record's certificate is ready.
environment.startedHubAn environment has been started.
environment.stoppedHubAn environment has been stopped.
environment.createdHubAn environment has been created.
environment.updatedHubAn environment has been updated.
environment.state.changedHubThe state of an environment has changed.
environment.errorHubA environment error has occurred.
environment.services.reconfiguredHubAn environment service container has been reconfigured.
environment.services.vpn.users.updatedHubA new user for an environment VPN has been updated.
environment.services.lb.ip.acquiredHubThe load balancer has successfully acquired an IP.
hub.state.changedHubThe state of a hub has changed.
hub.errorAccountA hub error has occurred.
hub.createdAccountA new hub has been created.
hub.updatedHubA hub has been updated.
hub.api_key.state.changedHubThe state of a hub API key has changed.
hub.api_key.errorHubA hub API key error has occurred.
hub.api_key.createdHubA new hub API key has been created.
hub.api_key.updatedHubA hub API key has been updated.
hub.membership.newAccountA new hub membership has been created.
hub.membership.updatedAccountA hub membership has been updated.
image.state.changedHubThe state of an image has changed.
image.updatedHubAn image has been updated.
image.errorHubAn image error has occurred.
infrastructure.ips.assignment.state.changedHubThe IP assignment on the some infrastructure has changed state.
infrastructure.ips.assignment.errorHubThere was an error with the IP assignment on some infrastructure.
infrastructure.ips.pool.state.changedHubThe state of an IP Pool has changed.
infrastructure.ips.pool.errorHubAn IP Pool error has occurred.
infrastructure.server.state.changedHubThe state of a server has changed.
infrastructure.server.errorHubA server error has occurred.
infrastructure.server.newHubA new server has been added.
infrastructure.server.reconfiguredHubA server has been reconfigured.
job.createdHubThe job has been created.
job.state.changedHubThe job's state has changed.
sdn.network.createdHubA new SDN network has been created.
sdn.network.errorHubAn
sdn.network.reconfiguredHubA SDN network has been reconfigured.
sdn.network.state.changedHubThe state of a SDN network has changed.
sdn.network.updatedHub The SDN network was updated.
stack.createdHubA new stack has been created.
stack.errorHubA stack error has occurred.
stack.state.changedHubThe state of a stack has changed.
stack.updatedHubA stack has updated.
stack.build.createdHubA new stack build has been created.
stack.build.state.changedHubThe state of a stack build has changed.
stack.build.errorHubA stack build error has occurred.
stack.build.deployedHubA stack build has been deployed.

Auth Only

Example Hub Connection
$ curl https://api.cycle.io/v1/channels/currnet/notifications \
  -H 
"Authorization: Bearer API_KEY"
 \
  -H 
"X-HUB-ID: HUB_ID"

UNAVAILABLE

Example Account Connection
$ curl https://api.cycle.io/v1/channels/account/notifications \
  -H 
"Authorization: Bearer API_KEY"
 \
  -H 
"X-HUB-ID: HUB_ID"
Curl Example Auth Response
{
  "data": {
    "token": "5d71fa31db2ab0000167b87es"
  }
}
Example Pipeline Event
{
  "topic": "container.reconfigured",
  "object": {
    "id": "5d71fa31db2ab0000167b87e",
    "state": "",
    "error": ""
  },
  "context": {
    "hub_id": "5d71fa31db2ab0000167b87e",
    "account_id": "5d71fa31db2ab0000167b87e",
    "environments": [
      "5d71fa31db2ab0000167b87e"
    ],
    "dns_zones": [],
    "clusters": [
      "production"
    ],
    "containers": [
      "5d71fa31db2ab0000167b87e"
    ]
  }
}

It is not possible to make websocket connections in cURL without the use of a third-party tool.