# Webhooks

# Check if Webhooks are Enabled

GET /api/v1/flock/settings/webhooks/is_enabled

Check if webhooks are enabled for a Flock.

Required Parameters

auth_token string
A valid auth token
flock_id string
A valid flock_id

Response

A JSON structure with the enabled state.

Example

curl https://EXAMPLE.canary.tools/api/v1/flock/settings/webhooks/is_enabled \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d flock_id=EXAMPLE_FLOCK_ID \
  -G
Copied!
1
2
3
4
Response
{
  "is_enabled": true,
  "result": "success"
}
Copied!
1
2
3
4

# Check if Webhooks are Global

GET /api/v1/flock/settings/webhooks/is_global

Check if webhooks are set to Global for a Flock.

Required Parameters

auth_token string
A valid auth token
flock_id string
A valid flock_id

Response

A JSON structure with the Global state.

Example

curl https://EXAMPLE.canary.tools/api/v1/flock/settings/webhooks/is_global \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d flock_id=EXAMPLE_FLOCK_ID \
  -G
Copied!
1
2
3
4
Response
{
  "is_global": true,
  "result": "success"
}
Copied!
1
2
3
4

# Disable Flock Webhooks

POST /api/v1/flock/settings/webhooks/disable

Disable a Flock's webhooks.

Required Parameters

auth_token string
A valid auth token
flock_id string
A valid flock_id

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/flock/settings/webhooks/disable \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d flock_id=EXAMPLE_FLOCK_ID 
Copied!
1
2
3
Response
{
  "result": "success"
}
Copied!
1
2
3

# Enable Flock Webhooks

POST /api/v1/flock/settings/webhooks/enable

Enable a Flock's webhooks.

Required Parameters

auth_token string
A valid auth token
flock_id string
A valid flock_id

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/flock/settings/webhooks/enable \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d flock_id=EXAMPLE_FLOCK_ID 
Copied!
1
2
3
Response
{
  "result": "success"
}
Copied!
1
2
3

# Use Global for Flock Webhooks

POST /api/v1/flock/settings/webhooks/use_global

Set the Flock's webhook state to Global.

Required Parameters

auth_token string
A valid auth token
flock_id string
A valid flock_id

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/flock/settings/webhooks/use_global \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d flock_id=EXAMPLE_FLOCK_ID 
Copied!
1
2
3
Response
{
  "result": "success"
}
Copied!
1
2
3

# Generic Webhooks

If you have an endpoint that accepts JSON data, we can setup a webhook to POST all notifications. Simple, but useful.

# Add Generic Webhook

POST /api/v1/flock/settings/webhooks/generic/add

Add a generic webhook to a Flock

Required Parameters

auth_token string
A valid auth token
flock_id string
A valid flock_id
url string
A valid URL that can accept POSTed data

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 the result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/flock/settings/webhooks/generic/add \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d flock_id=EXAMPLE_FLOCK_ID \
  -d url=EXAMPLE_URL
Copied!
1
2
3
4
Response
{
  "result": "success"
}
Copied!
1
2
3

# List Generic Webhooks

GET /api/v1/flock/settings/webhooks/generic DEPRECATED

Retrieve generic webhooks for a Flock.

Required Parameters

auth_token string
A valid auth token
flock_id string
A valid flock_id

Response

A JSON structure with the list of generic webhooks.

Example

curl https://EXAMPLE.canary.tools/api/v1/flock/settings/webhooks/generic \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d flock_id=EXAMPLE_FLOCK_ID \
  -G
Copied!
1
2
3
4
Response
{
  "generic_webhooks": [
    "<webhook_url>",
    "<webhook_url>"
  ],
  "result": "success",
  "webhooks_enabled": true
}
Copied!
1
2
3
4
5
6
7
8

# List Generic Webhooks

GET /api/v1/flock/settings/webhooks/generic/list

Retrieve generic webhooks for a Flock 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
flock_id string
A valid flock_id

Response

A JSON structure with the list of generic webhooks.

Example

curl https://EXAMPLE.canary.tools/api/v1/flock/settings/webhooks/generic/list \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d flock_id=EXAMPLE_FLOCK_ID \
  -G
Copied!
1
2
3
4
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

# Remove Generic Webhook

POST /api/v1/flock/settings/webhooks/generic/remove

Remove a generic webhook from a Flock

Required Parameters

auth_token string
A valid auth token
flock_id string
A valid flock_id
url string
A valid URL that can accept POSTed data

Response

A JSON structure with the result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/flock/settings/webhooks/generic/remove \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d flock_id=EXAMPLE_FLOCK_ID \
  -d url=EXAMPLE_URL
Copied!
1
2
3
4
Response
{
  "result": "success"
}
Copied!
1
2
3

# Test Generic Webhook

POST /api/v1/flock/settings/webhooks/generic/test

Test a generic webhook for a Flock

Required Parameters

auth_token string
A valid auth token
flock_id string
A valid flock_id
url string
A valid URL that can accept POSTed data

Response

A JSON structure with the result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/flock/settings/webhooks/generic/test \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d flock_id=EXAMPLE_FLOCK_ID \
  -d url=EXAMPLE_URL
Copied!
1
2
3
4
Response
{
  "result": "success",
  "webhook": "<webhook_url>"
}
Copied!
1
2
3
4

# MS Teams Webhooks

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

# Add MS Teams Webhook

POST /api/v1/flock/settings/webhooks/ms_teams/add

Add an MS Teams webhook to a Flock

Required Parameters

auth_token string
A valid auth token
flock_id string
A valid flock_id
url string
A valid MS Teams webhook

Response

A JSON structure with the result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/flock/settings/webhooks/ms_teams/add \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d flock_id=EXAMPLE_FLOCK_ID \
  -d url=EXAMPLE_URL
Copied!
1
2
3
4
Response
{
  "result": "success"
}
Copied!
1
2
3

# List MS Teams Webhooks

GET /api/v1/flock/settings/webhooks/ms_teams

Retrieve MS Teams webhooks for a Flock.

Required Parameters

auth_token string
A valid auth token
flock_id string
A valid flock_id

Response

A JSON structure with the list of MS Teams webhooks.

Example

curl https://EXAMPLE.canary.tools/api/v1/flock/settings/webhooks/ms_teams \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d flock_id=EXAMPLE_FLOCK_ID \
  -G
Copied!
1
2
3
4
Response
{
  "ms_teams_webhooks": [
    "<ms_teams_webhook_url>",
    "<ms_teams_webhook_url>"
  ],
  "result": "success",
  "webhooks_enabled": true
}
Copied!
1
2
3
4
5
6
7
8

# Remove MS Teams Webhook

POST /api/v1/flock/settings/webhooks/ms_teams/remove

Remove an MS Teams webhook from a Flock

Required Parameters

auth_token string
A valid auth token
flock_id string
A valid flock_id
url string
A valid MS Teams webhook

Response

A JSON structure with the result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/flock/settings/webhooks/ms_teams/remove \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d flock_id=EXAMPLE_FLOCK_ID \
  -d url=EXAMPLE_URL
Copied!
1
2
3
4
Response
{
  "result": "success"
}
Copied!
1
2
3

# Test MS Teams Webhook

POST /api/v1/flock/settings/webhooks/ms_teams/test

Test an MS Teams webhook for a Flock

Required Parameters

auth_token string
A valid auth token
flock_id string
A valid flock_id
url string
A valid MS Teams webhook

Response

A JSON structure with the result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/flock/settings/webhooks/ms_teams/test \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d flock_id=EXAMPLE_FLOCK_ID \
  -d url=EXAMPLE_URL
Copied!
1
2
3
4
Response
{
  "result": "success",
  "webhook": "<ms_teams_webhook_url>"
}
Copied!
1
2
3
4

# Slack Webhooks

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

# Add 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).

# List Slack Webhooks

GET /api/v1/flock/settings/webhooks/slack

Retrieve Slack webhooks for a Flock.

Required Parameters

auth_token string
A valid auth token
flock_id string
A valid flock_id

Response

A JSON structure with the list of Slack webhooks.

Example

curl https://EXAMPLE.canary.tools/api/v1/flock/settings/webhooks/slack \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d flock_id=EXAMPLE_FLOCK_ID \
  -G
Copied!
1
2
3
4
Response
{
  "result": "success",
  "slack_webhooks": [
    {
      "channel": "<channel>",
      "configuration_url": "<config_url>",
      "team": "<team_name>",
      "url": "<slack_webhook_url>"
    }
  ],
  "webhooks_enabled": true
}
Copied!
1
2
3
4
5
6
7
8
9
10
11
12

# Remove Slack Webhook

POST /api/v1/flock/settings/webhooks/slack/remove

Remove a Slack webhook from a Flock

Required Parameters

auth_token string
A valid auth token
flock_id string
A valid flock_id
team string
Slack team tied to the webhook
channel string
Slack channel tied to the webhook

Response

A JSON structure with the result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/flock/settings/webhooks/slack/remove \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d flock_id=EXAMPLE_FLOCK_ID \
  -d url=EXAMPLE_URL
Copied!
1
2
3
4
Response
{
  "result": "success"
}
Copied!
1
2
3

# Test Slack Webhook

POST /api/v1/flock/settings/webhooks/slack/test

Test an Slack webhook for a Flock

Required Parameters

auth_token string
A valid auth token
flock_id string
A valid flock_id
url string
A valid Slack webhook

Response

A JSON structure with the result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/flock/settings/webhooks/slack/test \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d flock_id=EXAMPLE_FLOCK_ID \
  -d url=EXAMPLE_URL
Copied!
1
2
3
4
Response
{
  "result": "success",
  "webhook": "<slack_webhook_url>"
}
Copied!
1
2
3
4

# Splunk Webhooks

Want to ingest your Console alerts into your Splunk? Setting it up is as as simple as setting the Splunk HTTP Event Collector (HEC) (opens new window) Webhook on your flock.

# Add Splunk Webhook

POST /api/v1/flock/settings/webhooks/splunk/add

Add a Splunk webhook to a Flock

Required Parameters

auth_token string
A valid auth token
flock_id string
A valid flock_id
host string
A domain or IP of the Splunk HEC
port string
The port the Splunk HEC runs on
token string
The Splunk HEC token

Response

A JSON structure with the result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/flock/settings/webhooks/splunk/add \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d flock_id=EXAMPLE_FLOCK_ID \
  -d host=EXAMPLE_HOST \
  -d port=EXAMPLE_PORT \
  -d token=EXAMPLE_TOKEN
Copied!
1
2
3
4
5
6
Response
{
  "result": "success"
}
Copied!
1
2
3

# List Splunk Webhook

GET /api/v1/flock/settings/webhooks/splunk

Retrieve Splunk webhook for a Flock.

Required Parameters

auth_token string
A valid auth token
flock_id string
A valid flock_id

Response

A JSON structure with Splunk webhook configuration.

Example

curl https://EXAMPLE.canary.tools/api/v1/flock/settings/webhooks/splunk \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d flock_id=EXAMPLE_FLOCK_ID \
  -G
Copied!
1
2
3
4
Response
{
  "result": "success",
  "splunk_webhook": {
    "host": "<domain/IP>",
    "port": "<port>",
    "token": "<HEC token>"
  },
  "webhooks_enabled": true
}
Copied!
1
2
3
4
5
6
7
8
9

# Remove Splunk Webhook

POST /api/v1/flock/settings/webhooks/splunk/remove

Remove the Splunk Webhook from a Flock

Required Parameters

auth_token string
A valid auth token
flock_id string
A valid flock_id

Response

A JSON structure with the result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/flock/settings/webhooks/splunk/remove \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d flock_id=EXAMPLE_FLOCK_ID \
Copied!
1
2
3
Response
{
  "result": "success"
}
Copied!
1
2
3

# Test Splunk Webhook

POST /api/v1/flock/settings/webhooks/splunk/test

Test the Splunk Webhook already configured on a Flock

Required Parameters

auth_token string
A valid auth token
flock_id string
A valid flock_id

Response

A JSON structure with the result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/flock/settings/webhooks/splunk/test \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d flock_id=EXAMPLE_FLOCK_ID \
Copied!
1
2
3
Response
{
  "result": "success",
}
Copied!
1
2
3