Webhook action with Twilio for SMS text messages

The FortiGate automation stitch framework can be used to interact with third-party services with webhooks to perform various tasks. A webhook action to Twilio can be used to automate tasks that send alerts and information to administrators by SMS text messages.

This topic includes two examples where the FortiGate uses webhooks to trigger Twilio to send SMS text messages to an administrator.

• Example 1: using an SD-WAN heath check to trigger a Twilio webhook action

• Example 2: using an incoming webhook to trigger a Twilio webhook action

Prerequisites

• An active Twilio account with a virtual phone number that is able to send SMS text messages to the receiver in the desired region

• A valid Twilio Account SID and Auth token for sending SMS text messages

These examples assume that the Twilio account is already configured. For more information, see Creating or Updating Resources with the POST Method in the Twilio documentation.

Example 1: using an SD-WAN heath check to trigger a Twilio webhook action

In this example, an administrator wants to monitor the FortiGate’s SD-WAN health, particularly when a dead health check is reported. An automation stitch will trigger the alert based on an SD-WAN log event (log ID 0113022931, SD-WAN SLA information warning) and perform a webhook action to inform Twilio to send an SMS message.

Sample SD-WAN log event

date=2023-01-13 time=10:39:26 eventtime=1673635167489361827 tz="-0800" logid="0113022931" type="event" subtype="sdwan" level="warning" vd="root" logdesc="SDWAN SLA information warning" eventtype="Health Check" healthcheck="Google" interface="VLAN1101" probeproto="ping" oldvalue="alive" newvalue="dead" msg="SD-WAN health-check member changed state."

To configure the automation stitch in the GUI:

1. Go to Security Fabric > Automation and click Create New.

2. Enter the stitch name (SD-WAN-HC-Down-SMS).

3. Configure the FortiOS event log trigger:

   1. Click Add Trigger.

   2. Click Create and select FortiOS Event Log.

   3. Enter the following:

      Name	SD-WAN-HC-Down
      Event	SDWAN SLA information warning
      Field filter(s)	Set Field name to newvalue. Set Value to dead.

   4. Click OK.

   5. Select the trigger in the list and click Apply.

4. Configure the webhook action:

   1. Click Add Action.

   2. Click Create and select Webhook.

   3. Enter the following:

      Name	Twilio-SMS-HC
      Protocol	HTTPS
      URL	Enter the URL provided by Twilio for sending SMS messages using the POST method. The URL can be found in the cURL code sample in the following format: https://api.twilio.com/2010-04-01/Accounts/<Twilio _Account_SID>/Messages.json.
      Method	POST
      HTTP body	Body=%%log%%&From=%2B1360x*******&To=%2B1604******* This string for the body text includes the SD-WAN log message, and the Twilio from and to phone numbers.
      HTTP header	Content-Type : application/x-www-form-urlencoded Authorization : Basic <Base64_encoded_authentication_code>

      

   4. Click OK.

   5. Select the action in the list and click Apply.

5. Click OK to save the stitch.

To configure the automation stitch in the CLI:

1. Configure the automation trigger:

   config system automation-trigger
       edit "SD-WAN-HC-Down"
           set event-type event-log
           set logid 22931
           config fields
               edit 1
                   set name "newvalue"
                   set value "dead"
               next
           end
       next
   end

2. Configure the automation action:

   config system automation-action
       edit "Twilio-SMS-HC"
           set action-type webhook
           set protocol https
           set uri "api.twilio.com/2010-04-01/Accounts/**********************************/Messages.json"
           set http-body "Body=%%log%%&From=%2B1360*******&To=%2B1604*******"
           set port 443
           config http-headers
               edit 1
                   set key "Content-Type"
                   set value "application/x-www-form-urlencoded"
               next
               edit 2
                   set key "Authorization"
                   set value "Basic ************"
               next
           end
       next
   end

3. Configure the automation stitch:

   config system automation-stitch
       edit "SD-WAN-HC-Down-SMS"
           set trigger "SD-WAN-HC-Down"
           config actions
               edit 1
                   set action "Twilio-SMS-HC"
                   set required enable
               next
           end
       next
   end

Verification:

1. Simulate an SD-WAN health check failure to trigger the automation stitch.

2. Twilio sends an SMS message to the administrator.

   

3. Go to Security Fabric > Automation and locate the SD-WAN-HC-Down-SMS stitch. The Trigger Count value has increased by one.

System log after the stitch was triggered:

date=2023-01-13 time=10:51:47 eventtime=1673635907720476287 tz="-0800" logid="0100046600" type="event" subtype="system" level="notice" vd="root" logdesc="Automation stitch triggered" stitch="SD-WAN-HC-Down-SMS" trigger="SD-WAN-HC-Down" stitchaction="Twilio-SMS-HC" from="log" msg="stitch:SD-WAN-HC-Down-SMS is triggered."

Example 2: using an incoming webhook to trigger a Twilio webhook action

In this example, an administrator wants to trigger an automation stitch remotely to retrieve the device uptime with an SMS text message. An incoming webhook will be used to send an HTTP POST request to trigger the event to occur. Subsequently, the FortiGate performs a CLI action followed by a webhook action to inform Twilio to send an SMS text message.

A REST API administrator with write privileges must be configured to apply an API key to this incoming webhook. See REST API administrator for more information.

To configure the automation stitch in the GUI:

1. Go to Security Fabric > Automation and click Create New.

2. Enter the stitch name (Check-Uptime).

3. Configure the incoming webhook trigger:

   1. Click Add Trigger.

   2. Click Create and select Incoming Webhook.

   3. Enter the trigger name (Check-Uptime-Webhook).

   4. Click OK.

   5. Select the trigger in the list and click Apply.

4. Configure the CLI script action:

   1. Click Add Action.
   2. Click Create and select CLI Script.
   3. Enter the following:

      Name	Uptime
      Script	get system performance status | grep Uptime
      Administrator profile	Select a profile with REST API write privileges (prof_admin)

   4. Click OK.
   5. Select the action in the list and click Apply.

5. Configure the webhook action:

   1. Click Add Action.

   2. Click Create and select Webhook.

   3. Enter the following:

      Name	Twilio-SMS-Uptime
      Protocol	HTTPS
      URL	Enter the URL provided by Twilio for sending SMS messages using the POST method. The URL can be found in the cURL code sample in the following format: https://api.twilio.com/2010-04-01/Accounts/<Twilio _Account_SID>/Messages.json.
      Method	POST
      HTTP body	Body=%%results%%&From=%2B1360x*******&To=%2B1604******* This string for the body text includes the results from the preceding CLI script action.
      HTTP header	Content-Type : application/x-www-form-urlencoded Authorization : Basic <Base64_encoded_authentication_code>

   4. Click OK.

   5. Select the action in the list and click Apply.

6. Click OK to save the stitch.

To configure the automation stitch in the CLI:

1. Configure the automation trigger:

   config system automation-trigger
       edit "Check-Uptime-Webhook"
           set event-type incoming-webhook
       next
   end

2. Configure the automation actions:

   config system automation-action
       edit "Uptime"
           set action-type cli-script
           set script "get system performance status | grep Uptime"
           set accprofile "prof_admin"
       next
       edit "Twilio-SMS-Uptime"
           set action-type webhook
           set protocol https
           set uri "api.twilio.com/2010-04-01/Accounts/**********************************/Messages.json"
           set http-body "Body=%%results%%&From=%2B1360*******&To=%2B1604*******"
           set port 443
           config http-headers
               edit 1
                   set key "Content-Type"
                   set value "application/x-www-form-urlencoded"
               next
               edit 2
                   set key "Authorization"
                   set value "Basic ************"
               next
           end
       next
   end

3. Configure the automation stitch:

   config system automation-stitch
       edit "Check-Uptime"
           set trigger "Check-Uptime-Webhook"
           config actions
               edit 1
                   set action "Uptime"
                   set required enable
               next
               edit 2
                   set action "Twilio-SMS-Uptime"
                   set required enable
               next
           end
       next
   end

Verification:

1. From a command prompt, issue the sample cURL command as recommended by the Check-Uptime-Webhook incoming webhook:

   >curl -k -X POST -H "Authorization: Bearer <API_token>" --data "{ 'srcip': '1.1.1.1', 'mac':'11:11:11:11:11:11', 'fctuid': '********************************'}" https://x.x.x.x/api/v2/monitor/system/automation-stitch/webhook/Check-Uptime-Webhook

   Response:

   {
     "http_method":"POST",
     "status":"success",
     "http_status":200,
     "serial":"FGVM04TM20000000",
     "version":"v7.0.10",
     "build":0450
   }

2. This triggers the automation stitch on the FortiGate to send a HTTP POST request to Twilio. In response, Twilio sends an SMS text message to the recipient.

   

3. From the Twilio dashboard, go to Messaging > Overview and verify the Recent Messages section to confirm that the SMS text message was delivered.

   

To view automation stitch diagnostics:

# diagnose debug enable
# diagnose debug application autod -1

2023-01-13 11:23:19 __action_cli_script_open()-180: cli script action:Uptime is called. svc ctx:0x10b4d5c0
accprof:prof_admin script:
get system performance status | grep Uptime

2023-01-13 11:23:19 0: get system performance status | grep Uptime
2023-01-13 11:23:20 __cli_script_close()-115: cli script:
autod.569
 output:
########## script name: autod.569 ##########

========== #1, 2023-01-13 11:23:19 ==========
FGDocs $  get system performance status | grep Uptime
Uptime: 49 days,  2 hours,  14 minutes

2023-01-13 11:23:20 0: config system auto-script
2023-01-13 11:23:20 0: delete "autod.569"
2023-01-13 11:23:20 0: end
2023-01-13 11:23:20 __action_cli_script_close()-207: cli script action is done. script:
get system performance status | grep Uptime
output:
########## script name: autod.569 ##########

========== #1, 2023-01-13 11:23:19 ==========
FGDocs $  get system performance status | grep Uptime
Uptime: 49 days,  2 hours,  14 minutes

2023-01-13 11:23:20 auto_generate_generic_curl_request()-443: Generating generic automation CURL request for action (Twilio-SMS-Uptime).
2023-01-13 11:23:20 auto_generate_generic_curl_request()-462: Formatting HTTP body with action parameters.
2023-01-13 11:23:20 auto_generate_generic_curl_request()-495: Generic automation CURL request POST data for action (Twilio-SMS-Uptime):
Body=########## script name: autod.569 ##########

========== #1, 2023-01-13 11:23:19 ==========
FGDocs $  get system performance status | grep Uptime
Uptime: 49 days,  2 hours,  14 minutes
&From=%2B1360*******&To=%2B1604*******

2023-01-13 11:23:20 auto_generate_generic_curl_request()-550: Generic automation CURL request Host header: api.twilio.com
2023-01-13 11:23:20 auto_generate_generic_curl_request()-553: Adding 2 user defined headers
2023-01-13 11:23:23 auto_curl_perform()-114: Failed to send curl request. http status code: 201

Although the final line in this debug output shows Failed to send curl request. http status code: 201, the HTTP status code 201 indicates that the request was successful and a response code was created.