Configure Webhooks

Webhooks deliver data to other applications, triggered by certain alerts using HTTP POST. Whenever an alert occurs, the source sends an HTTP request to the target application configured for the webhook. SD-WAN Orchestrator supports Webhooks that automatically send messages through HTTP POST to target apps when an event occurs. You can set the target URL in the Enterprise portal and automate actions in response to the alerts triggered by SD-WAN Orchestrator. The webhook recipients must support HTTPS and must have valid certificates, to ensure the privacy of potentially sensitive alert payloads. This also prevents the tampering of payloads.

The Webhooks page in the Alert Configuration window, allows you to configure the following details:


Option	Description
URL	Enter a valid HTTPS URL. This serves as the target application for the webhooks.
Code	Enter an expected HTTP response status code for each webhook recipient. By default, the SD-WAN Orchestrator expects webhook recipients to respond to HTTP POST requests with a status code as HTTP 200. When SD-WAN Orchestrator receives an unexpected status code from a recipient server or a proxy server, it considers that the alert delivery has failed, and generates an `ALERT_DELIVERY_FAILED` customer event. This event helps to identify when a webhook recipient server may fail to function as expected.
Secret	Specify a secret token for each configured webhook recipient, which is used to compute an HMAC for each webhook request sent to the corresponding recipient. The HMAC is embedded in a `X-Webhook-Signature` HTTP header, along with a version parameter, which identifies the signature algorithm and a timestamp. X-Webhook-Signature: v=<signature-version>&t=<timestamp>&s=<hmac> The recipient interprets the components as follows: `v`: Version of the algorithm used to produce the signature. The only supported value is 1. `t`: Millisecond-precision epoch timestamp corresponding to the time at which the request is issued. `s`: HMAC computed by SD-WAN Orchestrator. The HMAC is computed as follows: `HMAC-SHA256(request-body + '.' + timestamp, secret)`. The message used to compute the HMAC is formed by concatenating the request body, a single period, and the value of the timestamp parameter that appears in the signature header. The specific HMAC algorithm used to produce the code is HMAC-SHA256. After receiving a Webhook request, the listening server can verify the authenticity of the request by computing its own HMAC-SHA256 signature according to the same algorithm and compare the newly-computed signature with the one generated by the SD-WAN Orchestrator.
JSON Payload Template	This is a required field. SD-WAN Orchestrator delivers alert notifications to each webhook recipient, through a JSON payload contained within the body of an outgoing HTTP POST request. SD-WAN Orchestrator generates payload content dynamically, as notifications are sent by performing variable interpolation. The supported placeholder variables in the user-configured payload template are replaced with alert-specific values.
Verify	Click this option to validate the entered details.

Click Configure Payload Template link under the JSON Payload Template option to configure the following:


Option	Description
Alert Time	Enter the date and time at which the alert must be triggered.
Alert Type	Select the type of alert from the dropdown menu. By default, it is displayed as N/A.
Customer Logical ID	Enter the logical ID of the customer to whom the notification must be sent.
Customer	Enter the name of the customer to whom the notification must be sent.
Device Logical ID	Enter the logical ID of the Edge to which the alert must be applied.
Device Description	Enter a brief message describing the Edge to which the alert must be applied.
Device Serial Number	Enter the serial number of the Edge to which the alert must be applied.
Device Name	Enter the name of the Edge to which the alert must be applied.
Last Contact	Enter the date and time at which the affected Edge most recently communicated with the SD-WAN Orchestrator. This is applicable only for the Edge alerts.
VCO	Enter the Hostname or public IP of the SD-WAN Orchestrator from which the notification must be sent.
Message	Enter a brief message describing the event that must trigger the alert.
Entity Affected	Enter the name of the entity: Edge or link or VNF, to which the alert must be applied.

The following example shows a sample JSON payload template:

{
   "alertTime": "alertTime",
   "alertType": "alertType",      
   "customer": "customer",
   "customerLogicalId": "customerLogicalId",
   "entityAffected": "entityAffected",
   "deviceLogicalId": "deviceLogicalId",
   "lastContact": "lastContact",
   "message": "message",
   "vco": "vco",
   "deviceName": "deviceName",
   "deviceDescription": "deviceDescription",
   "deviceSerialNumber": "deviceSerialNumber"
}

Click Save, and then click Save Changes on the Webhooks page to save the webhook configurations.

Whenever an alert is triggered, an alert message along with relevant information is sent to the target URL.