Setting Webhook Notifications

Integrate Conviva alert events into external applications using webhooks.

For instance, display Conviva alerts in an alert aggregation system or trigger workflows in other applications, such as JIRA or other support ticket systems.

This topic helps you with:

• Adding Webhooks

• Managing Webhooks

• Displaying Webhooks

• Troubleshooting Webhooks

• Example Webhook Payload Formats

Adding Webhooks 

Only Admin users can add webhooks and customize alert payloads.  

Prerequisites

To get started with webhooks, create a webhook destination URL on your server. This URL will receive the webhook POST requests. The destination webhook URL must be a REST endpoint that provides an HTTP 2xx status code response when the request is successfully processed. The content type of the response payload can be application/json, XML, or other accepted formats. 

To add a webhook

1. In the Settings menu click Webhooks to see Feature Settings page with Webhooks.

   

2. Click the Add Webhook button.

   

   If no webhooks are configured, a message prompt appears. Click Add Webhokks to go to the Add Webhooks page so you can configure webhooks.

   

3. Enter a name for the webhook.

   The name must be 3 to 256 characters and begin with an alphanumeric character. The webhook name is displayed in the notification email when a failure occurs, so use names that can help identify the related alert.

   

4. Enter the email addresses to notify users when an issue occurs with the webhook notification.

   

5. Enter the webhook URL to which Conviva will post data.

   Optionally, select the URL authentication method and enter a username/password or authentication token.

   Note:  Username and password are encrypted in Conviva's system. 

   

6. Select the alert type(s) to include in the webhook payload.

   AI Alert Payload

   1. To include the AI alert payload, click the Include AI Alerts in the webhook checkbox.

   2. Click View Standard Fields, to view the standard AI alert payload key/value pairs. For explanation of the JSON structure, see Setting Webhook Notifications. If AI alert severity is enabled, the severity level of the alert is passed in the payload.

   3. To add custom key/value pairs, click Add Custom Field(s), and enter the custom key and value fields.

      
      

   Manual Alert Payload Customization

   1. To include the manual alert payload, click the Include Manual Alerts in the webhook checkbox.

   2. To view the standard manual alert payload key/value pairs, click View Standard Fields. For an explanation of the JSON structure, see Setting Webhook Notifications

   3. Select the check boxes to include optional key/value pairs, and customize the key names.

   4. Click Add Custom Field(s) to enter custom key/value pairs, and enter the custom key and value fields.

      

   5. Click Test Webhook to send test payload data to the webhook URL.

      

      Note:  Rerun the test whenever the webhook payload type or content changes.

   Validation confirms that:

   • Webhook URL is reachable.

   • Webhook URL can receive the payload data.

   • A response with an HTTP 2xx status code is received.

Valid Response

A valid response indicates that the webhook URL is operational.

To display the sent request and received response

1. Click Test Webhooks. Verify that the configured custom key/value pairs and customized key names appear in the request and response.

   

Error Response

If the test is not successful, an error response appears. Fix the error based on the status code and re-test the URL.

1. Status code 401: Re-enter the credentials. The entered credentials were not passed or invalid.

2. Status code 422: Contact Conviva. An invalid attribute or decoding exception occurred.

3. Status code 503: Check the webhook URL. The webhook connection failed to establish a new connection.

   After testing a webhook, you need to clear the webhook checkbox to make any additional changes to the payload settings.

   

   

4. Click Save to configure the webhook.

   

Managing Webhooks

Only Admin users can add, edit, disable, remove webhooks and customize alert payloads.  

To manage webhooks:

1. Click the Kebab icon for a webhook on the Webhooks page:

   1. Disable: Stop posting webhook data, while the webhook configuration is maintained in the system.

   2. Enable: Re-activate a disabled webhook.

   3. Edit: Modify the webhook settings or data.

   4. Delete:Remove all webhook configuration from the system.

   5. History: Display a change history log of the webhook modifications.

      

Displaying Webhooks

Users can view existing webhooks to monitor webhook status, check webhook settings, and display any error status information. 

To display the current webhook

1. In the Settings menu click Webhooks.

   The Feature Settings page is displayed with Webhooks.

   

2. Check the current webhook counts for:

   • Total: Total number of configured webhooks.

   • Enabled: The number of webhooks configured in the system.

   • Disabled: The number of webhooks configured in the system, but not posting data.

   • Errors: The number of webhooks in an error state.

     Click the Error link to display status information about the error.

     From the error message, admin users can click Editto make changes to the webhook.

3. To filter the displayed webhooks, click a webhook count.
   

   

Troubleshooting Webhooks

Retry Behavior

If a webhook POST request does not return an HTTP 2xx Success code, the webhook follows this retry behavior and resends the POST until an HTTP 2xx Success response is received or the last retry is reached.

Troubleshooting

If a webhook stops working, use these troubleshooting tips to help fix the issue. 

• Verify the webhook status on the Webhooks page. If an Error status is displayed, click the Error link to display more information about the error. 
• For HTTP status code 401, verify that the username/password or token are valid. Authorization changes may have occurred on the server hosting the destination URL. 
• For HTTP status code 422, an unexpected processing error occurred with the webhook. Contact Conviva Support for assistance. 
• For HTTP status code 503, the server hosting the destination URL may be down or unreachable. Verify connectivity to the destination server. 

If the initial webhook is unreachable, make sure the Conviva IP addresses are whitelisted to allow network and firewall access. Contact your Conviva representative for a list of the required Conviva IP addresses. 

Example Webhook Payload Formats

Refer to these examples for Webhook payload formats for AI and alerts.

Example Webhook Format for Video AI Alerts

If you copy and paste this example, change the values for your own testing purposes. Use the "custom fields" value to customize the payload.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
      "source": "Conviva",
       "version": "1.0.0",
      "alert_source": "AI Alert",
      "event_id": 1457888888,
      "account_name": "Test",
      "root_cause": "ISP and AppleTV",
      "cumulative_impacted_unique_devices": 1,
      "diagnostic_report_url": "http://127.20.10.1:8000/alerts4/1457888888",
      "metric_name": "Rebuffering Ratio",
      "active plays": 3,
      "alert_time": "02:45 Jan 18, 1970 PST",
      "severity": "info",
      "custom_fields": {
        "runbook url": "http://google.com"      }
}

Example Webhook Format for ECO AI Alerts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
      "source": "Conviva",
       "version": "1.0.0",
      "alert_source": "AI Alert",
      "event_id": 1457888888,
      "account_name": "Test",
      "root_cause": "iOS Native Player and iOS",
      "cumulative_impacted_unique_devices": 1,
      "diagnostic_report_url": https://pulse.conviva.com/alerts/1457888888,
      "metric_name": "Average Payload Time",
      "alert_time": "02:45 Jan 18, 1970 PST",
      "value": "15 sec",
      "severity": "info",
      "custom_fields": {
              "runbook_url": http://test.com      }
}

Example Webhook Format for Manual Alerts

If you copy and paste this example, be sure to change the values for your own testing purposes. Use the "custom fields" value to customize the payload. 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
    "source": "Conviva",
    "version": "1.0.0",
    "alert_source": "Manual Alert",
    "alert_id": 1,
    "event_id": 30,
    "priority": p1,
    "filter_id": 56523,
    "account_name": "c3.Publisher",
    "metric_name": "Pods Started",
    "filter_name": "All Traffic",
    "condition": "9.4 < 3345.0",
    "alert_time": "Oct 25 2017 12:22",
    "diagnostic_report_url": " https://www.conviva.com/pulse/alerts4/123888888",
    "sample_size": "1000 Minutes",
    "alert_name": "Publisher Network Television",
    "configured_samples": "200 Minutes",
    "cool_down": "0"
    "custom_fields": {
    "runbook url": "http://google.com"
    }
}

If you want the custom fields to be on the same level or hierarchy as the default alert fields, enable the flatten webhooks.

Note: When flatten webhooks is enabled, the version sent in the Payload is 2.0.0.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
    "source": "Conviva",
    "version": "2.0.0",
    "alert_source": "Manual Alert",
    "alert_id": 1,
    "event_id": 30,
    "priority": p1,
    "filter_id": 56523,
    "account_name": "c3.Publisher",
    "metric_name": "Pods Started",
    "filter_name": "All Traffic",
    "condition": "9.4 < 3345.0",
    "alert_time": "Oct 25 2017 12:22",
    "diagnostic_report_url": " https://www.conviva.com/pulse/alerts4/123888888",
    "sample_size": "1000 Minutes",
    "alert_name": "Publisher Network Television",
    "configured_samples": "200 Minutes",
    "cool_down": "0",
    "runbook url": "http://google.com"
}

If you want the custom fields to be in their own nested level, disable the flatten webhooks.

Note: When flatten webhooks is disabled, the version sent in the Payload is 1.0.0.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
    "source": "Conviva",
    "version": "1.0.0",
    "alert_source": "Manual Alert",
    "alert_id": 1,
    "event_id": 30,
    "priority": p1,
    "filter_id": 56523,
    "account_name": "c3.Publisher",
    "metric_name": "Pods Started",
    "filter_name": "All Traffic",
    "condition": "9.4 < 3345.0",
    "alert_time": "Oct 25 2017 12:22",
    "diagnostic_report_url": " https://www.conviva.com/pulse/alerts4/123888888",
    "sample_size": "1000 Minutes",
    "alert_name": "Publisher Network Television",
    "configured_samples": "200 Minutes",
    "cool_down": "0"
    "custom_fields": {
      "runbook url": "http://google.com"
    }
}

To enable or disable the flatten Webhooks, contact your Conviva representative.

Webhook Webhook Webhook