Canary API Docs

# Notification Channels

When an alert is triggered on your Birds, or a change happens on your Console, we can send you a notification to let you know something is up.

These notifications can be sent to different channels and they can also be customized so that you only receive the notifications that matter to you (take a look at Ignore Lists to filter alerts generated from your Birds).

The following endpoints will allow you to configure your notification channels such as Webhooks (Slack, MS Teams, Generic), SMS, Email and Syslog.

TIP

Viewing your Console's current notification setup is as easy as querying the Info endpoint.

Endpoints
POST /api/v1/settings/notifications/email/disable
POST /api/v1/settings/notifications/email/enable
POST /api/v1/settings/notifications/email/save
POST /api/v1/settings/notifications/operational_email/disable
POST /api/v1/settings/notifications/operational_email/enable
POST /api/v1/settings/notifications/operational_email/save
GET /api/v1/settings/notifications/info
POST /api/v1/settings/notifications/sms/disable
POST /api/v1/settings/notifications/sms/enable
POST /api/v1/settings/notifications/sms/save
GET /api/v1/settings/generic/list
POST /api/v1/settings/generic/add
POST /api/v1/settings/generic/remove
POST /api/v1/settings/generic/test
POST /api/v1/settings/ms_teams/add
POST /api/v1/settings/ms_teams/remove
POST /api/v1/settings/ms_teams/test
POST /api/v1/settings/slack/remove
POST /api/v1/settings/slack/test
POST /api/v1/pubsub/new_subscription
DELETE /api/v1/pubsub/remove_subscription
POST /api/v1/pubsub/test

# Email

Whenever an alert comes in, we can send you a notification directly to your inbox. Simple, but effective.

# Disable Email Notifications

POST /api/v1/settings/notifications/email/disable

Disable email notifications.

Required Parameters

auth_token string
A valid auth token

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/settings/notifications/email/disable \
  -d auth_token=EXAMPLE_AUTH_TOKEN 

  
        Copied!
1
2
Response
{
  "result": "success"
}

  
        Copied!
1
2
3

# Enable Email Notifications

POST /api/v1/settings/notifications/email/enable

Enable email notifications.

Required Parameters

auth_token string
A valid auth token

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/settings/notifications/email/enable \
  -d auth_token=EXAMPLE_AUTH_TOKEN 

  
        Copied!
1
2
Response
{
  "result": "success"
}

  
        Copied!
1
2
3

# Set Email Notifications List

POST /api/v1/settings/notifications/email/save

Set the list of email addresses to send notifications to.

Required Parameters

auth_token string
A valid auth token

Optional Parameters

addresses string
A comma separated list of email addresses
clear boolean
If set to true, clears the list of email addresses

TIP

At least one of the optional parameters is required.

Response

A JSON structure with result indicator and the current list of emails.

Example

curl https://EXAMPLE.canary.tools/api/v1/settings/notifications/email/save \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d addresses=EXAMPLE_ADDRESSES_LIST

  
        Copied!
1
2
3
Response
{
  "emails": "<email_address>,<email_address>",
  "result": "success"
}

  
        Copied!
1
2
3
4

# Operational Email

Set a separate list of email addresses to receive all operational alert email notifications.

# Disable Operational Email Notifications

POST /api/v1/settings/notifications/operational_email/disable

Disable operational email notifications.

Required Parameters

auth_token string
A valid auth token

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/settings/notifications/operational_email/disable \
  -d auth_token=EXAMPLE_AUTH_TOKEN 

  
        Copied!
1
2
Response
{
  "result": "success"
}

  
        Copied!
1
2
3

# Enable Operational Email Notifications

POST /api/v1/settings/notifications/operational_email/enable

Enable operational email notifications. If enabled, Canary Disconnects/Reconnects, Canary Settings Changed, Console Settings Changed and Flock Settings Changed alerts will be emailed to Operational Email Notifications addresses only.

Required Parameters

auth_token string
A valid auth token

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/settings/notifications/operational_email/enable \
  -d auth_token=EXAMPLE_AUTH_TOKEN 

  
        Copied!
1
2
Response
{
  "result": "success"
}

  
        Copied!
1
2
3

# Set Operational Email Notifications List

POST /api/v1/settings/notifications/operational_email/save

Set the list of operational email addresses to send notifications to.

Required Parameters

auth_token string
A valid auth token

Optional Parameters

addresses string
A comma separated list of email addresses
clear boolean
If set to true, clears the list of email addresses

TIP

At least one of the optional parameters is required.

Response

A JSON structure with result indicator and the current list of emails.

Example

curl https://EXAMPLE.canary.tools/api/v1/settings/notifications/operational_email/save \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d addresses=EXAMPLE_ADDRESSES_LIST

  
        Copied!
1
2
3
Response
{
  "emails": "<email_address>,<email_address>",
  "result": "success"
}

  
        Copied!
1
2
3
4

# Info

GET /api/v1/settings/notifications/info

View the current notification configuration for your Console.

Required Parameters

auth_token string
A valid auth token

Response

A JSON structure with notification information.

Example

curl https://EXAMPLE.canary.tools/api/v1/settings/notifications/info \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -G

  
        Copied!
1
2
3
Response
{
  "emails": {
    "addresses": "fail@domain.com,test@domain.com",
    "enabled": "True"
  },
  "result": "success",
  "sms": {
    "enabled": "False",
    "numbers": ""
  }
}

  
        Copied!
1
2
3
4
5
6
7
8
9
10
11

# SMS

Whenever an alert comes in, we can send you a notification directly to your cellphone. Simple, but effective.

# Disable SMS Notifications

POST /api/v1/settings/notifications/sms/disable

Disable SMS notifications.

Required Parameters

auth_token string
A valid auth token

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/settings/notifications/sms/disable \
  -d auth_token=EXAMPLE_AUTH_TOKEN 

  
        Copied!
1
2
Response
{
  "result": "success"
}

  
        Copied!
1
2
3

# Enable SMS Notifications

POST /api/v1/settings/notifications/sms/enable

Enable SMS notifications.

Required Parameters

auth_token string
A valid auth token

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/settings/notifications/sms/enable \
  -d auth_token=EXAMPLE_AUTH_TOKEN 

  
        Copied!
1
2
Response
{
  "result": "success"
}

  
        Copied!
1
2
3

# Set SMS Notifications List

POST /api/v1/settings/notifications/sms/save

Set the list of cellphone numbers to send notifications to.

Required Parameters

auth_token string
A valid auth token

Optional Parameters

numbers string
A comma separated list of cellphone numbers
clear boolean
If set to true, clears the list of cellphone numbers

TIP

At least one of the optional parameters is required.

Response

A JSON structure with result indicator and the current list of cellphone numbers.

Example

curl https://EXAMPLE.canary.tools/api/v1/settings/notifications/sms/save \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d numbers=EXAMPLE_CELLPHONE_NUMBERS_LIST

  
        Copied!
1
2
3
Response
{
  "result": "success"
}

  
        Copied!
1
2
3

# Syslog

We don't currently have endpoints publicly available to enable and manage your Syslog setup. Instead, we deal with all the setup and simply require the Syslog details from you to get it done. We have a KB article that will explain the setup process (opens new window).

# Webhooks

# Generic

If you simply want us to POST JSON data to a URL, the Generic Webhook is perfect for you.

# List Generic Webhooks

GET /api/v1/settings/generic/list

Retrieve generic webhooks and list the names of the headers configured for the webhook. (Header values are not shown as they may be sensitive.)

Required Parameters

auth_token string
A valid auth token

Response

A JSON structure with the list of generic webhooks.

Example

curl https://EXAMPLE.canary.tools/api/v1/settings/generic/list \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -G

  
        Copied!
1
2
3
Response
{
  "generic_webhooks": [
    {
      "header_names": [
          "Header-Name",
          "Header-Name-2",
          "Header-Name-3"
      ],
      "url": "<webhook_url>",
      "webhook_id": "<webhook_id>"
    },
    {
      "header_names": [],
      "url": "<webhook_url>",
      "webhook_id": "<webhook_id>"
    }
  ],
  "result": "success",
  "webhooks_enabled": true
}

  
        Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# Add a Generic Webhook

POST /api/v1/settings/generic/add

Add a new generic webhook.

Required Parameters

auth_token string
A valid auth token
url string
The URL of the webhook that we'll post data to

Optional Parameters

headers string
JSON structure of the headers to configure for the webhook.

Webhook headers JSON structure:

The headers are specified as "Name": "Value"

{
  "Header-Name-1": "Value",
  "Header-Name-2": "Value_2",
  "Header-Name-3": "Value_3"
}

  
        Copied!
1
2
3
4
5

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/settings/generic/add \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d url=EXAMPLE_URL

  
        Copied!
1
2
3
Response
{
  "result": "success",
  "webhook": "<url>"
}

  
        Copied!
1
2
3
4

# Remove a Generic Webhook

POST /api/v1/settings/generic/remove

Remove an existing generic webhook.

Required Parameters

auth_token string
A valid auth token
url string
The URL of the webhook that you want to remove

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/settings/generic/remove \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d url=EXAMPLE_URL

  
        Copied!
1
2
3
Response
{
  "result": "success"
}

  
        Copied!
1
2
3

# Test an Existing Generic Webhook

POST /api/v1/settings/generic/test

Test an existing generic webhook endpoint by sending it test data.

Required Parameters

auth_token string
A valid auth token
url string
The URL of the webhook that we'll send test data to

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/settings/generic/test \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d url=EXAMPLE_URL

  
        Copied!
1
2
3
Response
{
  "result": "success",
  "webhook": "<url>"
}

  
        Copied!
1
2
3
4

# MS Teams

Have an MS Teams account and want us to pipe notifications directly into your channels? Setting up your Console to do just that is as easy as supplying a valid MS Teams URL (opens new window).

# Add an MS Teams Webhook

POST /api/v1/settings/ms_teams/add

Add a new MS Teams webhook.

Required Parameters

auth_token string
A valid auth token
url string
The URL of the MS Teams webhook that we'll post data to

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/settings/ms_teams/add \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d url=EXAMPLE_URL

  
        Copied!
1
2
3
Response
{
  "result": "success",
  "webhook": "<url>"
}

  
        Copied!
1
2
3
4

# Remove an MS Teams Webhook

POST /api/v1/settings/ms_teams/remove

Remove an existing MS Teams webhook.

Required Parameters

auth_token string
A valid auth token
url string
The URL of the MS Teams webhook that you want to remove

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/settings/ms_teams/remove \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d url=EXAMPLE_URL

  
        Copied!
1
2
3
Response
{
  "result": "success"
}

  
        Copied!
1
2
3

# Test an Existing MS Teams Webhook

POST /api/v1/settings/ms_teams/test

Test an existing MS Teams webhook by sending it test data.

Required Parameters

auth_token string
A valid auth token
url string
The URL of the MS Teams webhook that we'll send test data to

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/settings/ms_teams/test \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d url=EXAMPLE_URL

  
        Copied!
1
2
3
Response
{
  "result": "success",
  "webhook": "<url>"
}

  
        Copied!
1
2
3
4

# Slack

If your business uses Slack and wants notifications sent directly into a specific channel in your team, then this is the section for you.

Within a few clicks (we currently don't expose the Add functionality via the API as the UI is pretty seamless) you'll have your Slack Webhook setup and ready to notify you on any new alerts.

# Add a Slack Webhook

We currently don't expose the Slack add process via the API directly as it requires a multi-step process which includes Authenticating with Slack and granting permissions for the webhook to POST data to your channels.

A step-by-step guide to adding a Slack webhook via the Console UI can be found here (opens new window).

# Remove an Existing Slack Webhook

POST /api/v1/settings/slack/remove

Remove an existing Slack webhook.

Required Parameters

auth_token string
A valid auth token
team string
Team associated with the Slack webhook
channel string
Channel associated with the Slack webhook

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/settings/slack/remove \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d team=EXAMPLE_TEAM \
  -d channel=EXAMPLE_CHANNEL

  
        Copied!
1
2
3
4
Response
{
  "result": "success"
}

  
        Copied!
1
2
3

# Test an Existing Slack Webhook

POST /api/v1/settings/slack/test

Test an existing Slack webhook by sending it test data.

Required Parameters

auth_token string
A valid auth token
url string
The URL of the Slack webhook that we'll send test data to

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/settings/slack/test \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d url=EXAMPLE_URL

  
        Copied!
1
2
3
Response
{
  "result": "success",
  "webhook": "<url>"
}

  
        Copied!
1
2
3
4

# Google Cloud Pub/Sub

We totally understand the need to fit notifications into existing pipelines, so in addition to email, SMS, webhooks, and using the API, we also have Pub/Sub.

If you'd like to have this enabled on your Console drop us a mail and we'll get you sorted!

# Add a Subscriber

POST /api/v1/pubsub/new_subscription

Adds a new Pub/Sub subscriber.

Required Parameters

auth_token string
A valid auth token
subscription_name string
The name of the subscriber

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/pubsub/new_subscription \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d subscription_name=EXAMPLE_SUB_NAME

  
        Copied!
1
2
3
Response
{
  "result": "success"
}

  
        Copied!
1
2
3

# Remove a Subscriber

DELETE /api/v1/pubsub/remove_subscription

Removes a Pub/Sub subscriber.

Required Parameters

auth_token string
A valid auth token
subscription_name string
The name of the subscriber

Response

A JSON structure with result indicator.

Example

curl -X DELETE https://EXAMPLE.canary.tools/api/v1/pubsub/remove_subscription \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d subscription_name=EXAMPLE_SUB_NAME

  
        Copied!
1
2
3
Response
{
  "result": "success"
}

  
        Copied!
1
2
3

# Send a test message to Subscribers

POST /api/v1/pubsub/test

Sends a test message to subscribers.

Required Parameters

auth_token string
A valid auth token

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/pubsub/test \
  -d auth_token=EXAMPLE_AUTH_TOKEN

  
        Copied!
1
2
Response
{
  "result": "success"
}

  
        Copied!
1
2
3

← Notification Settings →