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 , Splunk ), SMS , Email and Syslog .
TIP
Viewing your Console's current notification setup is as easy as querying the Info endpoint.
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.
Show details
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
1 2
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/notifications/email/disable'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11
{
"result" : "success"
}
1 2 3
Enable Email Notifications POST /api/v1/settings/notifications/email/enable
Enable email notifications.
Show details
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
1 2
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/notifications/email/enable'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11
{
"result" : "success"
}
1 2 3
Set Email Notifications List POST /api/v1/settings/notifications/email/save
Set the list of email addresses to send notifications to.
Show details
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
1 2 3
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/notifications/email/save'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN' ,
'addresses' : 'EXAMPLE_ADDRESSES_LIST'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11 12
{
"emails" : "<email_address>,<email_address>" ,
"result" : "success"
}
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.
Show details
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
1 2
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/notifications/operational_email/disable'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11
{
"result" : "success"
}
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.
Show details
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
1 2
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/notifications/operational_email/enable'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11
{
"result" : "success"
}
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.
Show details
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
1 2 3
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/notifications/operational_email/save'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN' ,
'addresses' : 'EXAMPLE_ADDRESSES_LIST'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11 12
{
"emails" : "<email_address>,<email_address>" ,
"result" : "success"
}
1 2 3 4
Info GET /api/v1/settings/notifications/info
View the current notification configuration for your Console.
Show details
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
1 2 3
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/notifications/info'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN'
}
r = requests. get( url, params= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11
{
"emails" : {
"addresses" : "fail@domain.com,test@domain.com" ,
"enabled" : "True"
} ,
"result" : "success" ,
"sms" : {
"enabled" : "False" ,
"numbers" : ""
}
}
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.
Show details
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
1 2
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/notifications/sms/disable'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11
{
"result" : "success"
}
1 2 3
Enable SMS Notifications POST /api/v1/settings/notifications/sms/enable
Enable SMS notifications.
Show details
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
1 2
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/notifications/sms/enable'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11
{
"result" : "success"
}
1 2 3
Set SMS Notifications List POST /api/v1/settings/notifications/sms/save
Set the list of cellphone numbers to send notifications to.
Show details
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
1 2 3
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/notifications/sms/save'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN' ,
'numbers' : 'EXAMPLE_CELLPHONE_NUMBERS_LIST'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11 12
{
"result" : "success"
}
1 2 3
Syslog We don't currently have endpoints publicly available to enable and set up 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 explains the setup process(opens new window) .
POST /api/v1/settings/notifications/audit/syslog
Enable or disable Syslog audit trail notifications.
Show details
Required Parameters auth_token string
A valid auth token
enabled boolean
If set to true, audit trail records will be sent to Syslog
Response A JSON structure with result indicator.
Example curl https://EXAMPLE.canary.tools/api/v1/settings/notifications/audit/syslog \
-d auth_token = EXAMPLE_AUTH_TOKEN \
-d enabled = true
1 2 3
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/notifications/audit/syslog'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN' ,
'enabled' : True
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11 12
{
"result" : "success" ,
"enabled" : true
}
1 2 3 4
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.)
Show details
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
1 2 3
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/generic/list'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN'
}
r = requests. get( url, params= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11
{
"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
}
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.
Show details
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"
}
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
1 2 3
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/generic/add'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN' ,
'url' : 'EXAMPLE_URL'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11 12
{
"result" : "success" ,
"webhook" : "<url>"
}
1 2 3 4
Remove a Generic Webhook POST /api/v1/settings/generic/remove
Remove an existing generic webhook.
Show details
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
1 2 3
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/generic/remove'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN' ,
'url' : 'EXAMPLE_URL'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11 12
{
"result" : "success"
}
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.
Show details
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
1 2 3
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/generic/test'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN' ,
'url' : 'EXAMPLE_URL'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11 12
{
"result" : "success" ,
"webhook" : "<url>"
}
1 2 3 4
POST /api/v1/settings/webhook/configure
Configure an existing generic webhook's settings by providing a setting and a value.
Show details
Required Parameters auth_token string
A valid auth token
url string
The URL of the webhook that we'll send test data to
setting string
The setting to configure. Currently only receive_audit_trail_records
value boolean
The value for setting
Response A JSON structure with result indicator.
Example curl https://EXAMPLE.canary.tools/api/v1/settings/webhook/configure \
-d auth_token = EXAMPLE_AUTH_TOKEN \
-d url = EXAMPLE_URL \
-d setting = receive_audit_trail_records \
-d value = true
1 2 3 4 5
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/webhook/configure'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN' ,
'url' : 'EXAMPLE_URL' ,
'setting' : 'receive_audit_trail_records' ,
'value' : True
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11 12 13 14
{
"result" : "success"
}
1 2 3
Splunk If you simply want us to POST JSON data to your Splunk server's HEC, the Splunk webhook is perfect for you.
Add a Splunk Webhook POST /api/v1/settings/splunk/add
Add a new Splunk webhook.
Show details
Required Parameters auth_token string
A valid auth token
host string
Hostname of the Splunk HEC
port int
Port of the Splunk HEC
token string
The Splunk HEC token
Response A JSON structure with result indicator.
Example curl https://EXAMPLE.canary.tools/api/v1/settings/splunk/add \
-d auth_token = EXAMPLE_AUTH_TOKEN \
-d host = SPLUNK_HEC_HOST \
-d port = 8088 \
-d token = SPLUNK_HEC_TOKEN
1 2 3 4 5
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/splunk/add'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN' ,
'host' : 'SPLUNK_HEC_HOST' ,
'port' : 8088 ,
'token' : 'SPLUNK_HEC_TOKEN'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11 12 13 14
{
"result" : "success"
}
1 2 3
Remove a Splunk Webhook POST /api/v1/settings/splunk/remove
Remove an existing Splunk webhook.
Show details
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/splunk/remove \
-d auth_token = EXAMPLE_AUTH_TOKEN
1 2
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/splunk/remove'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11
{
"result" : "success"
}
1 2 3
Test an Existing Splunk Webhook POST /api/v1/settings/splunk/test
Test an existing Splunk webhook endpoint by sending it test data.
Show details
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/splunk/test \
-d auth_token = EXAMPLE_AUTH_TOKEN
1 2
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/splunk/test'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11
{
"result" : "success"
}
1 2 3
POST /api/v1/settings/splunk/configure
Configure an existing Splunk webhook's settings by providing a setting and a value.
Show details
Required Parameters auth_token string
A valid auth token
setting string
The setting to configure. Currently only receive_audit_trail_records
value boolean
The value of the setting. true or false
Response A JSON structure with result indicator.
Example curl https://EXAMPLE.canary.tools/api/v1/settings/splunk/configure \
-d auth_token = EXAMPLE_AUTH_TOKEN \
-d setting = receive_audit_trail_records \
-d value = true
1 2 3 4
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/splunk/configure'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN' ,
'setting' : 'receive_audit_trail_records' ,
'value' : True
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11 12 13
{
"result" : "success" ,
}
1 2 3
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.
Show details
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
1 2 3
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/ms_teams/add'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN' ,
'url' : 'EXAMPLE_URL'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11 12
{
"result" : "success" ,
"webhook" : "<url>"
}
1 2 3 4
Remove an MS Teams Webhook POST /api/v1/settings/ms_teams/remove
Remove an existing MS Teams webhook.
Show details
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
1 2 3
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/ms_teams/remove'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN' ,
'url' : 'EXAMPLE_URL'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11 12
{
"result" : "success"
}
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.
Show details
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
1 2 3
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/ms_teams/test'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN' ,
'url' : 'EXAMPLE_URL'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11 12
{
"result" : "success" ,
"webhook" : "<url>"
}
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.
Show details
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
1 2 3 4
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/slack/remove'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN' ,
'team' : 'EXAMPLE_TEAM' ,
'channel' : 'EXAMPLE_CHANNEL'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11 12 13
{
"result" : "success"
}
1 2 3
Test an Existing Slack Webhook POST /api/v1/settings/slack/test
Test an existing Slack webhook by sending it test data.
Show details
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
1 2 3
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/slack/test'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN' ,
'url' : 'EXAMPLE_URL'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11 12
{
"result" : "success" ,
"webhook" : "<url>"
}
1 2 3 4
