Setting up Webhooks Service

Zoom utilizes webhooks as a medium to notify third-party applications (consumer applications) about events that occur in a Zoom account. Instead of making repeated calls to pull data frequently from the Zoom API, you can use webhooks to get information on events that happen in a Zoom account. Zoom sends webhook events as HTTP POST requests with a JSON body to the URL you specify. This URL is referred to as the Endpoint Notification URL.

You can configure the eG agent to use Webhooks for collecting metrics on events that occur within a target Zoom account.

To enable the eG agent to use webhooks, you need to follow the broad steps discussed hereunder:

  1. Install a Webhooks service on the eG agent host

  2. SSL-enable the Webhooks Service, so that Zoom communicates with the service over HTTPs only

  3. Configure Zoom to send specific event notifications to the Webhooks service URL

  4. Configure the eG agent to use the Webhooks service to report metrics on events

The sub-sections that follow will discuss each of these steps elaborately.

Installing the Webhooks service

Follow the steps below to install the Webhooks service:

  1. Login to the eG agent host.

  2. Run command prompt in elevated mode.

  3. Go to the <EG_AGENT_INSTALL_DIR>\Webhooks\bin directory.

  4. Run the CreateWebhookService.bat to install the service.

  5. Once the service is installed, you should be able to see the Webhooks service in Windows Service manager.

  6. Run the StartWebhookService.bat to start the Webhooks service.

The Webhooks service, once installed, exposes a URL. This Webhooks service URL should be publicly available/ accessible via HTTPS, so that Zoom can access it and send events to the endpoint. To enable this transmission, make sure that the firewall is configured to allow SSL traffic from the internet to the system hosting the Webhooks service. Also, make sure that the port at which the service listens is available and is opened.

This service URL should be configured as the Endpoint Notification URL in Zoom. To know how to configure this URL in Zoom, refer to the section Setting up the Zoom event subscription. Zoom sends events it triggers to the Webhooks Service via the notification URL. The Webhooks Service then stores the details of these events in an H2 database on the agent host. Every 15 minutes, the eG agent runs tests to read the H2 DB in the <EG_AGENT_INSTALL_DIR>/Webhooks/DB folder and reports measures. The figure below depicts how the eG agent uses the Webhooks Service.

Figure 1 : Webhooks service architecture

Note:

To troubleshoot issues with the Webhooks service, you can use the following logs:

  • Application logs written to the <EG_AGENT_INSTALL_DIR>/Webhooks/logs folder

  • Event details written to <EG_AGENT_INSTALL_DIR>/Webhooks/DB folder

  1.  

You can even restart, stop, or remove the Webhooks service. For this, follow the steps below:

  1. Login to the eG agent host.

  2. Open the command prompt in elevated mode.

  3. Switch to the <EG_AGENT_INSTALL_DIR>\Webhooks\bin directory.

  4. Run the StopWebhookService.bat file to stop the Webhooks service.

  5. Run the RestartWebhookService.bat file to bounce/restart Webhooks service.
  6. Run the RemoveWebhookService.bat file to uninstall the Webhooks service.

SSL-Enabling the Webhooks Service

Communication between Zoom and the Webhooks Service should be over HTTPS only. This is why, you need to SSL-enable the Webhooks service. To SSL-enable the Webhooks service, you need a signed SSL certificate. This certificate can be obtained in one of the following ways:

  1. You can obtain a signed certificate from an internal certifying authority (eg., Microsoft Active Directory Certificate Services) and use this certificate to SSL-enable the service, (OR)
  2. You can obtain a signed certificate from a valid, external certifying authority (eg., Verisign) and use this certificate to SSL-enable the service

If you go with option (a), use the procedure detailed in the SSL-Enabling the Webhooks Service Using a Certificate Signed by an Internal CA topic. If you pick option (b), use the procedure detailed in SSL-Enabling the Webhooks Service Using a Certificate Obtained from a Valid Certifying Authority topic.

Configuring Zoom to Send Events to the Webhooks Service

For this, follow the steps below:

  1. Once the Webhooks service is setup, login to Zoom Marketplace and click 'Manage' from the menu shown in the Figure 2.

    Figure 2 : Manage the webhook setup

  2. When Figure 3 appears, look for the special monitoring app that you created (when setting up the Zoom API). Once you find the app, click on the app name as shown in Figure 3.

    Figure 3 : Setting up webhook service for newly created app

  3. Make note of the Client ID shown in Figure 4. Then, click Feature.

    Figure 4 : Copying the Client ID

  4. Make note of the Secret Token displayed in Figure 5. Then, push the Event Subscriptions slider to the right to enable subscription, and click the Add Event Subscription button.

    .

    Figure 5 : Copying the secret token

  5. In thesubsequent screen, enter Subscription name and Event notification endpoint URL (i.e., the Webhooks service URL). To know what is the Webhooks service URL, open the webhook.properties file in the <EG_AGENT_INSTALL_DIR>\Webhooks\config folder on the agent host, and look for the value specified against the WebhookURL parameter. Specify this value in the Event notification endpoint URL text box in Figure 6. Then, click the Add Events button.

    Figure 6 : Entering the details for notification

  6. In the Event types screen that appears next, select the check boxes corresponding to the types of events you want to monitor. Some sample events have been chosen for monitoring in Figure 7 to Figure 11

    Figure 7 : Adding meeting events

    Figure 8 : Adding webinar events

    Figure 9 : Adding recording events

    Figure 10 : Adding Zoom room events

    Figure 11 : Adding user events

  7. Next, proceed to validate the Webhook URL. For that, go to General Features in Features section, click the edit icon (indicated by Figure 12), and click Validate. If the URL is successfully validated, click Save to save the URL configuration.

    Figure 12 : Validating the service.

    Figure 13 : Validate the webhook service

Configuring the eG Agent to Monitor Events Using the Webhooks Service

Once the Webhooks configuration is completed, add a Zoom component for monitoring in the eG Enterprise system, and configure any of the Webhook tests as shown in Figure 14

Figure 14 : Configuring Webhook test

Make sure that you configure the test with the Client ID and Secret Token that you made note of earlier (see steps 3 and 4 of the previous section). The eG agent uses these credentials to access the event data stored in the H2 database and pull metrics.