API

Webhooks

Open certain actions taking place within your account, we can trigger a JSON POST callback to a URL or your choice.

Your Webhook handlers are expected to respond within 5 seconds. If they take longer than this, then the failures count will be incremented and the webhook queued for reprocessing. Reprocessing happens at 5 minutes, 30 minutes, 1 hour, 2 hours, 6 hours - and after that the webhook will be disabled.

The headers of the request from our servers will contain the following two important headers: X-Civo-Event and X-Civo-Signature. X-Civo-Event is a UUID that is unique to this event. We don't track them ourside, but retries of the same event will have the same ID, so you can track it and not process it twice. X-Civo-Signature is an OpenSSL HMAC SHA1 digest of the entire payload using either the secret of the webhook. The secret is randomly generated when the webhook is created if one isn't specified. A simple example of how to calculate this in Ruby would be:

signature = OpenSSL::HMAC.hexdigest(
  OpenSSL::Digest.new('sha1'),
  webhook.secret,
  request.body
)

The following events are available to subscribe to:

NameDescription
*any event happens
instance.createdafter the instance has been requested to be built from OpenStack's Nova
instance.activewhen the instance returns an `ACTIVE` status after `BUILDING`
instance.updatedwhen the instance is renamed
instance.deletedwhen the instance has been requested to be deleted
instance.firewall.updatedafter OpenStack's Nova has been told to change the firewall for an instance
instance.rebootedafter OpenStack's Nova returns an ACTIVE status for an instance after it had been REBOOTING
instance.rebuiltafter OpenStack's Nova has been instructed to rebuild an instance (note: not when it's completed)
instance.stoppedafter OpenStack's Nova has been instructed to stop an instance (note: not when it's finished shutting down)
instance.startedafter OpenStack's Nova has been instructed to start an instance (note: not when it's completed booting up and all daemons running)
instance.restoredafter OpenStack's Nova has been instructed to restore an instance from a snapshot (note: not when it's completed)
instance.tags.updatedwhen an instance's tags have changed
instance.resizedafter an instance's status changes to ACTIVE after a resize was requested
instance.ip_address.updatedwhen a newly launched instance get's its public IP
instance.high_cpu.startedwhen an instance's CPU goes above 80%
instance.high_cpu.endedwhen an instance's CPU drops back below 80%
instance.rescuedafter OpenStack's Nova has been instructed to rescue an instance (note: not when it's completed being rescued)
instance.unrescuedafter OpenStack's Nova has been instructed to revert an instance from a rescued state (note: not when it's completed reverting from a rescued state)
domain.createdafter a domain name has been added to our DNS service
domain.deletedafter a domain has been removed from our DNS service
domain_record.createdafter a DNS record has been added for a domain in our DNS service
domain_record.updatedafter a DNS record has been changed for a domain in our DNS service
domain_record.deletedafter a DNS record has been removed for a domain from our DNS service
firewall.createdafter OpenStack's Neutron has been instructed to create the firewall
firewall.updatedafter OpenStack's Neutron has been instructed to rename the firewall
firewall.deletedafter OpenStack's Neutron has been instructed to remove the firewall
firewall_rule.createdafter OpenStack's Neutron has been instructed to add a rule to a firewall
firewall_rule.deletedafter OpenStack's Neutron has been instructed to remove a rule from a firewall
load_balancer.createdafter a URL has been added to our load balancer service
load_balancer.updatedafter the settings for a URL has been changed in our load balancer service
load_balancer.deletedafter a URL has been removed from our load balancer service
network.createdafter a network is added to our database
network.updatedafter a network is renamed from our database
network.deletedafter a network is removed from our database
ssh_key.createdafter an SSH key has been uploaded to our site
ssh_key.updatedafter an SSH key has been changed
ssh_key.deletedafter an SSH key has been deleted
snapshot.createdafter a snapshot has been requested
snapshot.completedafter a snapshot completes according to OpenStack's Glance service
snapshot.deletedafter a snapshot has been removed
snapshot.failedafter a snapshot fails to complete
template.createdafter a user template has been created
template.updatedafter a user template has been updated
template.deletedafter a user template has been removed
volume.createdafter a volume has been created
volume.updatedafter a volume has been updated
volume.deletedafter a volume has been removed
volume.attachedafter a volume has been attached
volume.detachedafter a volume has been detached
volume.resizedafter a volume has been resized
volume.renamedafter a volume has been renamed

Listing webhooks

Listing the webhooks is possible by making a GET request to the https://api.civo.com/v2/webhooks resource.

Request

This request doesn't take any parameters.

Response

The response from the server will be a JSON array of webhooks.

[
  {
    "id": "b8de2e4e-72f4-4911-83ee-f4fc030fc4a2",
    "events": ["instance.created", "instance.deleted"],
    "url": "https://api.example.com/webhook",
    "secret": "DfeFUON8gorc5Zj0hk4GT1M9QImnRL6J",
    "disabled": false,
    "failures": 0,
    "last_failure_reason": "",
  },
  // ...
]

Example of listing webhooks

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/webhooks
var request = require('request');

request.get(
  'https://api.civo.com/v2/webhooks',
  {},
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = get('v2/webhooks', headers)

Create a new webhook

Any user can create webhooks for their account.

New webhooks are created by sending a POST request to https://api.civo.com/v2/webhooks.

Request

The required parameters are listed below.

Name Description
events This is a list of events that the webhook should be triggered for. Alternative you can use a list containing a single entry of "*" to signify trigger for all events. (required)
url This is the URL to send the webhook to (required).
secret This is if you want to specify your own secret, if not a random one will be created for you (optional).

Response

The response is a JSON representation of the webhook, including the secret.

{
  "id": "b8de2e4e-72f4-4911-83ee-f4fc030fc4a2",
  "events": ["*"],
  "url": "https://api.example.com/webhook",
  "secret": "DfeFUON8gorc5Zj0hk4GT1M9QImnRL6J",
  "disabled": false,
  "failures": 0,
  "last_failure_reason": "",
}

Example of creating a webhook

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/webhooks \
  -F events='["*"]' -F url=https://api.example.com/webhook
var request = require('request');

request.post(
  'https://api.civo.com/v2/webhooks',
  {
    "events": ["*"],
    "url": "https://api.example.com/webhook"
  },
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

safe_url = CGI::escape("https://api.example.com/webhook")
resp, data = http.post('/v2/webhooks', 'events=["*"]&url=' + safe_url, headers)

Test a webhook

Once a webhook is created, you can test it by sending a POST request to https://api.civo.com/v2/webhooks/:id/test and this will call your webhook handler with a dummy payload.

Request

No parameters are required for this request.

Response

The response is a JSON object that simply confirms that the request to test the webhook was received.

{
  "result": "success"
}

Example of testing a webhook

curl -H "Authorization: bearer 12345" -X POST https://api.civo.com/v2/webhooks/12345/test
var request = require('request');

request.post(
  'https://api.civo.com/v2/webhooks/12345/test',
  {},
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.post('/v2/webhooks/12345/test', '', headers)

Update a webhook

After creating a webhook, any user can update it.

Webhooks are updated by sending a PUT request to https://api.civo.com/v2/webhooks/:id.

Request

The parameters are as per creation of webhooks.

Response

The response is a JSON representation of the updated webhook, including the secret.

{
  "id": "b8de2e4e-72f4-4911-83ee-f4fc030fc4a2",
  "events": ["*"],
  "url": "https://api.example.com/webhook",
  "secret": "DfeFUON8gorc5Zj0hk4GT1M9QImnRL6J",
  "disabled": false,
  "failures": 0,
  "last_failure_reason": "",
}

Example of updating a webhook

curl -H "Authorization: bearer 12345" -X put https://api.civo.com/v2/webhooks/12345 \
  -F events='["instance.created"]'
var request = require('request');

request.put(
  'https://api.civo.com/v2/webhooks/12345',
  {
    "events": ["instance.created"]
  },
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.put('/v2/webhooks/12345', 'events=["instance.created"]', headers)

Deleting a webhook

An account holder can remove one of their webhooks by sending a DELETE request to https://api.civo.com/v2/webhooks/:id.

Request

This request takes no parameters, only the ID of the webhook to delete is in the URL. No confirmation step is required, this step will remove the webhook immediately.

Response

The response from the server will be a JSON block. The response will include a result field and the HTTP status will be 202 Accepted.

{
  "result": "success"
}

Example of deleting a webhook

curl -H "Authorization: bearer 12345" \
  -X DELETE https://api.civo.com/v2/webhooks/12345
var request = require('request');

request.del(
  'https://api.civo.com/v2/webhooks/12345',
  function (error, response, body) {
    if (!error && response.statusCode == 202) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.delete('/v2/webhooks/12345', headers)