The Notification Pipeline

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

Auth Return
  • data
    object

    The data object holding the token.

    Show child fields
Notificaiton Channel Message
  • 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
  • flags
    object
    optional

    Flags used internally, if returned will show null.

Authenticating

Connecting to the websocket is a two step process.

First you authenticate against the endpoint:

/v1/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 its probably a good idea write a short script to handle the two steps.

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/hubs/current/notifications?token=$token

Account

https://api.cycle.io/v1/hubs/current/notifications?token=$token

Connecting to the Notification Pipeline

The hub pipeline will send notifications about the events happening on the hub (types listed below). It's at your discretion to use that information and decide whether to make a follow up API call for the rest.

Headers

HeaderTypeDescription
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.instance.health.status.changedHubThe container instance's health has changed. Possible status's are healthy and unhealthy
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.certificate.readyHubA DNS Zone record's certificate is ready.
dns.zone.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.
environment.variable.createdHubAn environment secret variable has been created.
environment.variable.updatedHubAn environment secret variable has been updated.
environment.variable.state.changedHubAn environment secret variable's state has changed.
hub.state.changedHubThe state of a hub has changed.
hub.updatedHubA hub has been updated.
hub.membership.newHubThere has been a new hub membership event.
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.
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.
ips_pool.state.changedHubThe state of an IP Pool has changed.
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.
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.
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.
pipeline.state.changedHubA pipelines state has changed.
pipeline.errorHubA pipeline error has occurred.
pipeline.updatedHubA pipeline has been updated.
pipeline.createdHubA pipeline has been created.
pipeline.key.state.changedHubA pipeline key has encounterd a state change.
pipeline.key.errorHubA pipeline key error has occurred.
pipeline.key.updatedHubA pipeline key has been updated.
pipeline.key.createdHubA pipeline key has been created.
pipeline.run.state.changedHubA pipeline run state change has occured.
pipeline.run.errorHubA pipeline run error has occured.
pipeline.run.createdHubA pipeline run has been created.

Auth

Example Hub Connection
# This will return the AUTH data object
$ curl  https://api.cycle.io/v1/hubs/current/notifications \
  -H 
"Authorization: Bearer API_KEY"
 \
  -H 
"X-Hub-Id: HUB_ID"
# Capture the Auth data object returned above and save the token to use in this call (AUTH_TOKEN)
# WILL NOT WORK WITHOUT HTTP1.1 Flag
$ curl  -o - --http1.1 --include \
  --no-buffer \
  --header "Connection: Upgrade" \
  --header "Upgrade: websocket" \
  --header "Host: api.cycle.io" \
  --header "Origin: https://api.cycle.io" \
  --header 
"Sec-WebSocket-Key: API_KEY"
 \
  --header "Sec-WebSocket-Version: 13" \
  -H 
"x-cycle-token: AUTH_TOKEN"
 \
  -H 
"Authorization: Bearer API_KEY"
 \
  -H 
"X-Hub-Id: HUB_ID"
 \
  https://api.cycle.io/v1/hubs/current/notifications?token=$token

GET /v1/hubs/current/notifications

Curl Example Auth Response
{
  "data": {
    "token": "Im3tH1omJkGH9pdtesNcPcgxl3iC7nGDsgH5pZU8g odJNzIaicp7ixkDMgrvKaadRrLcU1JtWmTsRvlC4AKh_D_DobPM0j_\n    rgvQL4Cq017P6Wi5OuasC5VGxm4UATkdNEQRXbm820\n    9kYyif2g9YdEA 9RhrUz4cWbKMwjy3o41Eceno2nxvaTub_meLBmxljC"
  }
}
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"
    ]
  }
}