Introduction

• Email and Webhook notifications enable push-model mechanism to receive real time notifications for alarms that are generated in SDWAN fabric .
• Polling vManage REST APIs to retrieve alarms is sub optimal because alarms occur at random events and trying to figure out how often to make REST API calls is messy.
• By enabling Email notifications, vManage sends email in real time and with Webhooks, vManage can send a HTTP POST request to the external system in real time once an alarm is received.
• Webhooks are sometimes referred as “Reverse APIs,” and we must design an API route to consume or process the data sent via webhook.

Prerequisites

• This feature is supported from vManage 18.3 release onward

Requirements

To use this code you will need:

• Python 3.7+
• Cisco SD-WAN 18.3+

Install and Setup

Clone the code to local machine.

git clone https://github.com/suchandanreddy/sdwan-webhooks.git
cd sdwan-webhooks

Setup Python Virtual Environment (requires Python 3.7+)

python3.7 -m venv venv
source venv/bin/activate
pip3 install -r requirements.txt

Setup local environment variables to provide Webex Teams Authorization and Room ID details.

Examples:

For macOS and Ubuntu Environment:

export bearer_token="authorization bearer token"
export room_id="webex teams room-id"
export gmail_username="gmail username"
export gmail_password="gmail password"
export sender_address="email sender address"
export to_address="email receiver address"

For Windows Environment:

set bearer_token="authorization bearer token"
set room_id="webex teams room-id"
set gmail_username="gmail username"
set gmail_password="gmail password"
set sender_address="email sender address"
set to_address="email receiver address"

vManage Configuration

Steps to enable webhook notifications for pushing alarms to external systems.

Step-1:

• Select “Email Notifications” from “Monitor -> Alarms”

Step-2:

• Select Add Email Notification

• Enter name for example, notifications
• Select severity level for example, Critical, Major, Medium and Minor
• Select Alarm Name for example, Control TLOC Down, Control TLOC Up, OMP Site Down, OMP Site Up, OMP Node Down, OMP Node Up
• Click on Add Email list to add email-ids which needs to receive notifications.

• Select Add Email

• Add email-ids ( Note: Maximum email-ids is 10 )

Step-4:

• Enable webhook checkbox.
• Provide the webhook server URL, username and password for webhook server.

(Note: If webhook server doesn’t have authentication configured, provide dummy username and password)

• Provide the Webhook Server URL
• Select All Devices or Custom option and click on Add to complete the webhook settings.

Step-5:

• Enable email notifications in Admin settings of vManage.

• In this example, we are using Gmail SMTP server (smtp.gmail.com) with SSL Security

This completes the configuration on vManage to enable Email and Webhook notifications

Notifications Dashboard

List of webhooks or email notifications configured can be seen in section Alarms > Email Notifications

Test Webhook

From vManage shell, run curl command and send dummy HTTP POST request to Webhook server to verify if Webhook server is reachable.

Sample output

vmanage# vshell
vmanage:~$ curl -v -X POST -H 'Content-type: application/json' http://<webhook-server-ip>:<webhook-server-port>/
*   Trying <webhook-server-ip>...
* TCP_NODELAY set
* Connected to <webhook-server-ip> (<webhook-server-ip>) port <webhook-server-port> (#0)
> POST / HTTP/1.1
> Host: <webhook-server-ip>:<webhook-server-port>
> User-Agent: curl/7.58.0
> Accept: */*
> Content-type: application/json
>
* HTTP 1.0, assume close after body
< HTTP/1.0 500 INTERNAL SERVER ERROR
< Content-Type: application/json
< Content-Length: 44
< Server: Werkzeug/0.15.2 Python/3.7.3
< Date: Sun, 14 Jul 2019 07:40:02 GMT
<
"Expecting value: line 1 column 1 (char 0)"
* Closing connection 0

Setup Webhook server

Now let’s setup Webhook server to accept notifications sent from vManage

• In order to accept HTTP post requests sent from vManage, we need to enable HTTP web server and design API route.
• Below code spins up flask web server listening on port 5001 for HTTP POST request
• Defined alarms() function accepts the POST request at route http://server-ip:port/ and extracts the data from request, then sends message
  to Webex Teams Room.

@app.route('/',methods=['POST'])
def alarms():
   try:
      data = json.loads(request.data)
      print(data)
      message =  '''Team, alarm event : **''' + data['eventname'] + '** ------ **' + data['message'] + '''** is recieved from vManage and here are the complete details <br><br>'''  + str(data)
      api = CiscoSparkAPI(access_token=bearer_token)
      res=api.messages.create(roomId=room_id, markdown=message)
      print(res)
   except Exception as exc:
      return jsonify(str(exc)), 500 

   return jsonify("Message sent to Webex Teams"), 200

Logs from Webhook Server:

Spin up HTTP webhook server using py -3.7 webhooks.py in windows environment or python3 webhooks.py in macOS environment

py -3.7 webhooks.py
 * Serving Flask app "webhooks" (lazy loading)
 * Environment: production
   WARNING: Do not use the development server in a production environment.
   Use a production WSGI server instead.
 * Debug mode: on
 * Restarting with stat
 * Debugger is active!
 * Debugger PIN: 338-300-672
 * Running on http://0.0.0.0:5001/ (Press CTRL+C to quit)

Sample JSON output on webhook server on receiving notifications from vManage.

OMP sessions Down Alarm:

{
   "values": [
     {
       "system-ip": "1.1.1.7",
       "site-id": "400",
       "host-name": "DCvedge1"
     }
   ],
   "values_short_display": [
     {
       "site-id": "400"
     }
   ],
   "message": "All OMP sessions to the site are down",
   "type": "site_down",
   "eventname": "rulename",
   "rulename": "site_down",
   "component": "OMP",
   "severity": "Critical",
   "severity_number": 1,
   "entry_time": 1563072991407,
   "statcycletime": 1563072991407,
   "receive_time": 1563072991407,
   "rule_name_display": "OMP_Site_Down",
   "uuid": "421cef7d-2111-455c-ae25-294ff4e2b4ca",
   "active": true,
   "devices": [
     {
       "system-ip": "1.1.1.7"
     }
   ],
   "consumed_events": [
     {
       "builtBy": "EventDataCollector",
       "vmanage-system-ip": "1.1.1.3",
       "entry_time": 1563072711000,
       "eventname": "omp-peer-state-change",
       "linkupdate": true,
       "component": "OMP",
       "severity-level": "major",
       "system-ip": "1.1.1.3",
       "host-name": "vsmart",
       "peer": "1.1.1.7",
       "peer-new-state": "down",
       "receive_time": 1563072931407,
       "eventId": "b54a8d6b-0256-40bc-b006-4ae9e37e8648",
       "eventCreationTime": 1563072931409
     }
   ],
   "acknowledged": false,
   "possible_causes": [
     "Trying to determine possible root causes"
   ]
 }

Alarms on vManage

• Above webhook logs corresponds to these alarms that were received by vManage.

Alert on Webex Teams Space

• The script sends the message to provided Webex Teams Space/Room. Here is sample output.

Email Notification

• vManage sends below email based on the notification settings enabled.

Email alert sent by webhook.py script

• We can leverage Webhook notifications sent by vManage and send email as per requirements.
• Webhook.py script contains email component and it sends below sample email notification to provided email-id.

References

SD-WAN Docs : https://sdwan-docs.cisco.com/Product_Documentation/vManage_How-Tos/Operation/Configure_Email_Notifications_for_Alarms

Youtube Video on Email and Webhook Notifications: https://youtu.be/s4T0dDKEKEg?list=PLAQ92p_FEespc_mlyyEHTSdc1bQmuphNH