Setting Webhook Notifications

Use webhooks to integrate Conviva alert events into external applications, such as displaying Conviva alerts in an alert aggregation system or triggering workflows in other applications, such as JIRA or other support ticket applications.

This topic helps you with:

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 display the Webhooks page.

2. Click the Add Webhook button.

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. Configure AI Alerts payload.

1. To view the standard AI alert payload key/value pairs, click View Standard Fields. For an 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.

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

   

3. Click Test Webhook to send test payload data to the webhook URL. 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 Show More. 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 the Add Webhook button 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 Action 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.

2. To add additional webhooks, click the Add Webhook button and enter the required data. See Setting Webhook Notifications for the detailed configuration steps.

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.

After the last retry attempt for the webhook request fails, Conviva disables the webhook URL and sends an email to the email addresses specified during the webhook configuration indicating that the webhook URL is unreachable and disabled. The POST message for the last event is included in the email. Any new alerts that fire while the webhook is disabled are not sent to the webhook URL or stored in Conviva Video

After the webhook URL is disabled, admin access is required to enable the webhook URL within Conviva Video to re-start external webhook notifications when alerts fire.

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 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      }
}

Webhook Webhook Webhook