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

# 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

    Response
    {
      "result": "success"
    }
    
    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

      Response
      {
        "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.

      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

        Response
        {
          "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.

        Required Parameters

        auth_token string
        A valid auth token

        Response

        A JSON structure with result indicator.

        Example

          Response
          {
            "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.

          Required Parameters

          auth_token string
          A valid auth token

          Response

          A JSON structure with result indicator.

          Example

            Response
            {
              "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.

            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

              Response
              {
                "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.

              Required Parameters

              auth_token string
              A valid auth token

              Response

              A JSON structure with notification information.

              Example

                Response
                {
                  "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.

                Required Parameters

                auth_token string
                A valid auth token

                Response

                A JSON structure with result indicator.

                Example

                  Response
                  {
                    "result": "success"
                  }
                  
                  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

                    Response
                    {
                      "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.

                    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

                      Response
                      {
                        "result": "success"
                      }
                      
                      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

                        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
                        }
                        
                        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"
                        }
                        
                        1
                        2
                        3
                        4
                        5

                        Response

                        A JSON structure with result indicator.

                        Example

                          Response
                          {
                            "result": "success",
                            "webhook": "<url>"
                          }
                          
                          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

                            Response
                            {
                              "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.

                            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

                              Response
                              {
                                "result": "success",
                                "webhook": "<url>"
                              }
                              
                              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

                                Response
                                {
                                  "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.

                                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

                                  Response
                                  {
                                    "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.

                                  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

                                    Response
                                    {
                                      "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.

                                    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

                                      Response
                                      {
                                        "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.

                                      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

                                        Response
                                        {
                                          "result": "success",
                                          "webhook": "<url>"
                                        }
                                        
                                        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

                                          Response
                                          {
                                            "result": "success"
                                          }
                                          
                                          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

                                            Response
                                            {
                                              "result": "success"
                                            }
                                            
                                            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

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