| Release Notes | NuGet (stable) | MyGet (prerelease) |
|---|---|---|
 |
 |
 |
The ZoomNet library simplifies connecting with the Zoom.us API and interacting with the various endpoints. Additionaly, the library includes a parser that allows you to process inbound webhook messages sent to you by the Zoom API.
The easiest way to include ZoomNet in your C# project is by adding the nuget package to your project:
PM> Install-Package ZoomNet
ZoomNet currently supports:
- .NET framework 4.8
- any framework supporting
.NET Standard 2.1(which includes.NET Core 3.xandASP.NET Core 3.x) .NET 6.0.NET 7.0
The last version of ZoomNet that supported .NET 4.6.1, .NET 4.7.2 and .NET Standard 2.0 was 0.35.0
Before you start using the ZoomNet client, you must decide how you are going to connect to the Zoom API. ZoomNet supports three ways of connecting to Zoom: JWT, OAuth and Server-to-Server OAuth.
This is the simplest way to connect to the Zoom API. Zoom expects you to use a key and a secret to generate a JSON object with a signed payload and to provide this JSON object with every API request. The good news is that ZoomNet takes care of the intricacies of generating this JSON object: you simply provide the key and the secret and ZoomNet takes care of the rest. Super easy!
As the Zoom documentation mentions, this is perfect if you're looking to build an app that provides server-to-server interaction with Zoom APIs.
Here is an except from the Zoom documentation that explains how to get your API key and secret:
JWT apps provide an API Key and Secret required to authenticate with JWT. To access the API Key and Secret, Create a JWT App on the Marketplace. After providing basic information about your app, locate your API Key and Secret in the App Credentials page.
When you have the API key and secret, you can instantiate a 'connection info' object like so:
var apiKey = "... your API key ...";
var apiSecret = "... your API secret ...";
var connectionInfo = new JwtConnectionInfo(apiKey, apiSecret);
var zoomClient = new ZoomClient(connectionInfo);Warning: Zoom has announced that this authentication method would be obsolete in June 2023. The recommendation is to swith to Server-to-Server OAuth.
Using OAuth is much more complicated than using JWT but at the same time, it is more flexible because you can define which permissions your app requires. When a user installs your app, they are presented with the list of permissions your app requires and they are given the opportunity to accept.
The Zoom documentation has a document about how to create an OAuth app and another document about the OAuth autorization flow but I personnality was very confused by the later document so here is a brief step-by-step summary:
- you create an OAuth app, define which permissions your app requires and publish the app in the Zoom marketplace.
- user installs your app. During installation, user is presentd with a screen listing the permissons your app requires. User must click
accept. - Zoom generates an "authorization code". This code can be used only once to generate the first access token and refresh token. I CAN'T STRESS THIS ENOUGH: the authorization code can be used only one time. This was the confusing part to me: somehow I didn't understand that this code could be used only one time and I was attempting to use it repeatedly. Zoom would accept the code the first time and would reject it subsequently, which lead to many hours of frustration while trying to figure out why the code was sometimes rejected.
- The access token is valid for 60 minutes and must therefore be "refreshed" periodically.
When you initially add an OAuth application to your Zoom account, you will be issued an "authorization code". You can provide this autorization code to ZoomNet like so:
var clientId = "... your client ID ...";
var clientSecret = "... your client secret ...";
var authorizationCode = "... the code that Zoom issued when you added the OAuth app to your account ...";
var redirectUri = "... the URI you have configured when setting up your OAuth app ..."; // Please note that Zoom sometimes accepts a null value and sometimes rejects it with a 'Redirect URI mismatch' error
var connectionInfo = new OAuthConnectionInfo(clientId, clientSecret, authorizationCode,
(newRefreshToken, newAccessToken) =>
{
/*
This callback is invoked when the authorization code
is converted into an access token and also when the
access token is subsequently refreshed.
You should use this callback to save the refresh token
to a safe place so you can provide it the next time you
need to instantiate an OAuthConnectionInfo.
The access token on the other hand does not need to be
preserved because it is ephemeral (meaning it expires
after 60 minutes). Even if you preserve it, it is very
likely to be expired (and therefore useless) before the
next time you need to instantiate an OAuthConnectionInfo.
For demonstration purposes, here's how you could use your
operating system's environment variables to store the token:
*/
Environment.SetEnvironmentVariable("ZOOM_OAUTH_REFRESHTOKEN", newRefreshToken, EnvironmentVariableTarget.User);
},
redirectUri);
var zoomClient = new ZoomClient(connectionInfo);Warning: This sample I just provided can be used only when Zoom issues a new the autorization code. ZoomNet will take care of converting this code into an access token at which point the autorization code is no longer valid.
Once the autorization code is converted into an access token and a refresh token, you can instantiate a 'connection info' object like so:
var clientId = "... your client ID ...";
var clientSecret = "... your client secret ...";
var refreshToken = Environment.GetEnvironmentVariable("ZOOM_OAUTH_REFRESHTOKEN", EnvironmentVariableTarget.User);
var connectionInfo = new OAuthConnectionInfo(clientId, clientSecret, refreshToken, null,
(newRefreshToken, newAccessToken) =>
{
/*
As previously stated, it's important to preserve the refresh token.
*/
Environment.SetEnvironmentVariable("ZOOM_OAUTH_REFRESHTOKEN", newRefreshToken, EnvironmentVariableTarget.User);
});
var zoomClient = new ZoomClient(connectionInfo);This authentication method is the replacement for JWT authentication which Zoom announced will be made obsolete in June 2023.
From Zoom's documentation:
A Server-to-Server OAuth app enables you to securely integrate with Zoom APIs and get your account owner access token without user interaction. This is different from the OAuth app type, which requires user authentication. See Using OAuth 2.0 for details.
ZoomNet takes care of getting a new access token and it also refreshes a previously issued token when it expires (Server-to-Server access token are valid for one hour).
var clientId = "... your client ID ...";
var clientSecret = "... your client secret ...";
var accountId = "... your account id ...";
var connectionInfo = new OAuthConnectionInfo(clientId, clientSecret, accountId,
(_, newAccessToken) =>
{
/*
Server-to-Server OAuth does not use a refresh token. That's why I used '_' as the first parameter
in this delegate declaration. Furthermore, ZoomNet will take care of getting a new access token
and to refresh it whenever it expires therefore there is no need for you to preserve it.
In fact, this delegate is completely optional when using Server-to-Server OAuth. Feel free to pass
a null value in lieu of a delegate.
*/
});
var zoomClient = new ZoomClient(connectionInfo);The delegate being optional in the server-to-server scenario you can therefore simplify the connection info declaration like so:
var connectionInfo = new OAuthConnectionInfo(clientId, clientSecret, accountId, null);
var zoomClient = new ZoomClient(connectionInfo);Here's a basic example of a .net 6.0 API controller which parses the webhook from Zoom:
using Microsoft.AspNetCore.Mvc;
namespace WebApplication1.Controllers
{
[Route("api/[controller]")]
[ApiController]
public class ZoomWebhooksController : ControllerBase
{
[HttpPost]
public async Task<IActionResult> ReceiveEvent()
{
var parser = new ZoomNet.WebhookParser();
var event = await parser.ParseEventWebhookAsync(Request.Body).ConfigureAwait(false);
// ... do something with the event ...
return Ok();
}
}
}It is possible for you to verify that a webhook is legitimate and originated from Zoom. Any webhook that fails to be verified should be considered suspicious and should be discarded.
To get started, you need to make sure that a Secret Token is associated with your Zoom Marketplace app (click the 'Regenerate' button if your app doesn't have such a token already) as demonstrated in this screenshot.
When your Marketplace app has a Secret Token, Zoom will include two additional headers in the request posted to your endpoint and you must use the values in these headers to verify that the content your received is legitimate.
If you want to know what to do with these two values to determine if a webhook is legitimate or not, please review this page in the documentation.
But, ZoomNet strives to make your life easier so we have already implemented this logic.
The WebhookParser class has a method called VerifyAndParseEventWebhookAsyncwhich will automatically verify the data and throw a security exception if verification fails. If the verification fails, you should consider the webhook data to be invalid. Here's how it works:
using Microsoft.AspNetCore.Mvc;
namespace WebApplication1.Controllers
{
[Route("api/[controller]")]
[ApiController]
public class ZoomWebhookController : ControllerBase
{
[HttpPost]
public async Task<IActionResult> ReceiveEvent()
{
// Your webhook app's secret token
var secretToken = "... your app's secret token ...";
// Get the signature and the timestamp from the request headers
// SIGNATURE_HEADER_NAME and TIMESTAMP_HEADER_NAME are two convenient constants provided by ZoomNet so you don't have to remember the actual names of the headers
var signature = Request.Headers[ZoomNet.WebhookParser.SIGNATURE_HEADER_NAME].SingleOrDefault();
var timestamp = Request.Headers[ZoomNet.WebhookParser.TIMESTAMP_HEADER_NAME].SingleOrDefault();
var parser = new ZoomNet.WebhookParser();
// The signature will be automatically validated and a security exception thrown if unable to validate
var zoomEvent = await parser.VerifyAndParseEventWebhookAsync(Request.Body, secretToken, signature, timestamp).ConfigureAwait(false);
// ... do something with the event...
return Ok();
}
}
}When you initially configure the URL where you want Zoom to post the webhooks, Zoom will send a request to this URL and you are expected to respond to this validation challenge in a way that can be validated by the Zoom API. Zoom calls this a "Challenge-Response check (CRC)". Assuming this initial validation is successful, the Zoom API will repeat this validation process every 72 hours. You can of course manually craft this reponse by following Zoom's instructions.
However, if you want to avoid learning the intricacies of the reponse expected by Zoom and you simply want this response to be conveniently generated for you, ZoomNet can help!
The EndpointUrlValidationEvent class has a method called GenerateUrlValidationResponse which will generate the string that you must include in your HTTP200 response.
Here's how it works:
using Microsoft.AspNetCore.Mvc;
namespace WebApplication1.Controllers
{
[Route("api/[controller]")]
[ApiController]
public class ZoomWebhooksController : ControllerBase
{
[HttpPost]
public async Task<IActionResult> ReceiveEvent()
{
// Your webhook app's secret token
var secretToken = "... your app's secret token ...";
var parser = new ZoomNet.WebhookParser();
var event = await parser.ParseEventWebhookAsync(Request.Body).ConfigureAwait(false);
var endpointUrlValidationEvent = zoomEvent as EndpointUrlValidationEvent;
var responsePayload = endpointUrlValidationEvent.GenerateUrlValidationResponse(secretToken);
return Ok(responsePayload);
}
}
}Here's the "ultimate" webhook controller which combines all the above features:
using Microsoft.AspNetCore.Mvc;
namespace WebApplication1.Controllers
{
[Route("api/[controller]")]
[ApiController]
public class ZoomWebhooksController : ControllerBase
{
[HttpPost]
public async Task<IActionResult> ReceiveEvent()
{
// Your webhook app's secret token
var secretToken = "... your app's secret token ...";
// SIGNATURE_HEADER_NAME and TIMESTAMP_HEADER_NAME are two convenient constants provided by ZoomNet so you don't have to remember the actual name of the headers
var signature = Request.Headers[ZoomNet.WebhookParser.SIGNATURE_HEADER_NAME].SingleOrDefault();
var timestamp = Request.Headers[ZoomNet.WebhookParser.TIMESTAMP_HEADER_NAME].SingleOrDefault();
var parser = new ZoomNet.WebhookParser();
Event zoomEvent;
if (!string.IsNullOrEmpty(signature) && !string.IsNullOrEmpty(timestamp))
{
try
{
zoomEvent = await parser.VerifyAndParseEventWebhookAsync(Request.Body, secretToken, signature, timestamp).ConfigureAwait(false);
}
catch (SecurityException e)
{
// Unable to validate the data. Therefore you should consider the request as suspicious
throw;
}
}
else
{
zoomEvent = await parser.ParseEventWebhookAsync(Request.Body).ConfigureAwait(false);
}
if (zoomEvent.EventType == EventType.EndpointUrlValidation)
{
// It's important to include the payload along with your HTTP200 response. This is how you let Zoom know that your URL is valid
var endpointUrlValidationEvent = zoomEvent as EndpointUrlValidationEvent;
var responsePayload = endpointUrlValidationEvent.GenerateUrlValidationResponse(secretToken);
return Ok(responsePayload);
}
else
{
// ... do something with the event ...
return Ok();
}
}
}
}As of this writing (October 2022), webhooks over websocket is in public beta testing and you can signup if you want to participate in the beta (see here).
ZoomNet offers a convenient client to receive and process webhooks events received over a websocket connection. This websocket client will automatically manage the connection, ensuring it is re-established if it's closed for some reason. Additionaly, it will manage the OAuth token and will automatically refresh it when it expires.
Here's how to use it in a C# console application:
using System.Net;
using ZoomNet;
using ZoomNet.Models.Webhooks;
var clientId = "... your client id ...";
var clientSecret = "... your client secret ...";
var accountId = "... your account id ...";
var subscriptionId = "... your subscription id ..."; // See instructions below how to get this value
// This is the async delegate that gets invoked when a webhook event is received
var eventProcessor = new Func<Event, CancellationToken, Task>(async (webhookEvent, cancellationToken) =>
{
if (!cancellationToken.IsCancellationRequested)
{
// Add your custom logic to process this event
}
});
// Configure cancellation (this allows you to press CTRL+C or CTRL+Break to stop the websocket client)
var cts = new CancellationTokenSource();
var exitEvent = new ManualResetEvent(false);
Console.CancelKeyPress += (s, e) =>
{
e.Cancel = true;
cts.Cancel();
exitEvent.Set();
};
// Start the websocket client
using (var client = new ZoomWebSocketClient(clientId, clientSecret, accountId, subscriptionId, eventProcessor, proxy, logger))
{
await client.StartAsync(cts.Token).ConfigureAwait(false);
exitEvent.WaitOne();
}When you configure your webhook over websocket in the Zoom Marketplace, Zoom will generate a URL like you can see in this screenshot:
Your subscription Id is the last part of the URL. In the example above, the generated URL is similar to wss://api.zoom.us/v2/webhooks/events?subscription_id=1234567890 and therefore the subscription id is 1234567890.