DEV Community: Elisa Levet

Using ngrok to receive Zoom Events

Elisa Levet — Tue, 31 Jan 2023 00:37:39 +0000

Zoom utilizes webhooks as a medium to notify third-party applications about events that occur in a Zoom account.

So, instead of making repeated calls to pull data from the Zoom API, you can use webhooks to get information on events that happen in a Zoom account.

This guide covers how to implement Zoom webhooks using ngrok as our secure URL to receive events from our Zoom account.

We will use our Webhook-sample-node.js app available on Gitbhub and we will be setting up a sample app in the Zoom Marketplace.

Step 1: Setting up our local environment

Install the sample app by running the following commands in your terminal:

git clone https://github.com/zoom/webhook-sample-node.js.git
cd webhook-sample-node.js
npm install

Create a .env file by running the following command in your terminal:

touch .env

And add the following placeholder

ZOOM_WEBHOOK_SECRET_TOKEN=

Note: Do not run your app quite yet, we need to head to the Zoom Marketplace and create an app first!

Step 2: Create an app in the Marketplace.

For this tutorial will use a Webhook only app.

Log in to your Zoom account and head to the Zoom Marketplace
Click the dropdown that says Develop and then click Build App
Select the Webhook Only app and give your app a name
Make sure to fill up the required Basic information (Company name, your name, email address)
On the Feature tab, copy the Secret Token and paste it in your .env file, under the ZOOM_WEBHOOK_SECRET_TOKEN placeholder; this value will be used later to validate our endpoint URL and to start receiving event notifications.
Click the Event subscription slider and click on Add Event Subscritions, give your subscription a name; and Add events to your app to subscribe, for example:
- Meeting has been created
- Meeting has been updated
- Meeting has been deleted.

Note: for now, we will be skipping the Event Notification Endpoint URL Validation, but we will come back to this later in the guide.

Step 3: Running our sample app and ngrok

Make sure you’ve saved your project after copying the value of the Secret Token from our newly created Webhook Only sample app, into the .env file.

Now you can run your app with the following command in your terminal:

npm run start

Now that your app is running locally on port 4000, we need to expose our local server to the internet to accept post requests, we will be using ngrok for this. (If you are not an ngrok user yet, just sign up for ngrok for free and follow the steps to install ngork and connect your account)

Start your ngrok by running the following command in your terminal:

ngrok http 4000

Copy the ngrok https url displayed in the terminal and paste it in your Event notification url input, followed by the /webhook path, (it should look like this https://exampleurl.ngrok.io/webhook)

Step 4: Validate your endpoint URL

Once you have added your ngrok https url followed by /webhook path, we will have to validate our endpoint.

Click on the Validate button and expect to get a “Validated” message.
Click on Save and then Continue to make sure that your app is activated on the account and that it’s ready to receive events from Zoom.

What happened here is:
Zoom requires to manually trigger the webhook validation when you add a new event or make changes to an existing one.

Zoom uses a challenge-response check (CRC) for webhook validation and when you click the Validate button in your app, a CRC occurs and Zoom will make a POST request to your https endpoint with a challenge-request body and your app will need to response with the challenge response and a 200 or 204 HTTP response code, within 3 seconds

This is how the CRC event sent by Zoom looks like:

{
  "payload": {
    "plainToken": "qgg8vlvZRS6UYooatFL8Aw"
  },
  "event_ts": 1654503849680,
  "event": "endpoint.url_validation"
}

Our sample app, will be listening to the event ‘ednpoint.url_validation’ and once it receives it, it we will create a HMAC SHA-256 hash using the Zoom webhook secret token and the plainToken received in the CRC request body; to lastly respond to Zoom with a Challenge Response and 200 status

if(request.body.event === 'endpoint.url_validation') {
  const hashForValidate = crypto.createHmac('sha256', ZOOM_WEBHOOK_SECRET_TOKEN).update(request.body.payload.plainToken).digest('hex')

  response.status(200)
  response.json({
    "plainToken": request.body.payload.plainToken,
    "encryptedToken": hashForValidate
  })
}

Challenge response body example:

{
  "plainToken": "qgg8vlvZRS6UYooatFL8Aw",
  "encryptedToken": "23a89b634c017e5364a15599e2bb04bb1558d9c3a121faa5"
}

Step 5: Receiving events in our sample app

Head to your Zoom account and trigger the respective Webhook, in this case as we chose the Meeting has been created event, you will have to schedule a Zoom meeting to be able to receive the event notification.

Once you create a meeting, you will see the Webhook headers and payload logged in terminal, something like this:

Request headers

{
   "host":"db05-2603-7000-8f03-fe4c-b56e-6f3b-bded-7b6d.ngrok.io",
   "user-agent":"Zoom Marketplace/1.0a",
   "content-length":"564",
   "authorization":"{LEGACY_WEBHOOK_VERIFICATION_TOKEN}",
   "clientid":"{clientID}",
   "content-type":"application/json; charset=utf-8",
   "x-forwarded-for":"{X_FORWARDED_FOR}",
   "x-forwarded-proto":"https",
   "x-zm-request-timestamp":"{X_ZM_REQUEST_TIMESTAMP}",
   "x-zm-signature":"{X_ZM_SIGNATURE}",
   "x-zm-trackingid":"{X_ZM_TRACKINGID}",
   "Accept-encoding":"gzip"
}

Response body

{
   "event":"meeting.created",
   "payload":{
      "account_id":"{ACCOUNT_ID}",
      "operator":"{EMAIL}",
      "operator_id":"{OPERATOR_ID}",
      "object":{
         "uuid":"{MEETING_UUID}",
         "id":"{MEETING_ID}",
         "host_id":"{HOST_ID",
         "topic":"My Meeting",
         "type":2,
         "start_time":"2023-01-26T21:00:00Z",
         "duration":60,
         "timezone":"America/New_York",
         "join_url":"{JOIN_URL}",
         "password":"{PASSWORD}",
         "settings":[
            "Object"
         ],
         "is_simulive":false
      }
   },
   "event_ts":1674764224723
}

What happened here is:

After receiving the webhook event, the sample app constructed a message string with “v0”, the webhook request header “x-zm-request-timestamp” value and the webhook request body

const message = `v0:${request.headers['x-zm-request-timestamp']}:${JSON.stringify(request.body)}`

Once the app constructed the message, it created a hash message, by setting the webhook’s secret token as the secret/salt and the message as the string to hash and outputed in hex format

const hashForVerify = crypto.createHmac('sha256', ZOOM_WEBHOOK_SECRET_TOKEN).update(message).digest('hex')

Created a signature using the hashed Message by prepending "v0=" to it:

const signature = `v0=${hashForVerify}`

Compared the signature that we created with the value from our request header “x-zm-signature”

If the value of signature matches with the value of the request header “x-zm-signature”, we will start receiving events.

You should now have a running app enabled to receive events in a secure URL.

It is important to remember that every time that you make changes your App in the Marketplace (adding new events or restarting our ngrok secure tunnel) you will have to validate the endpoint URL again.

Thank you for follow along and happy coding! 🙂

Setting up a Postgres database to receive Zoom webhooks

Elisa Levet — Thu, 15 Sep 2022 00:15:59 +0000

Thank you for joining us again for part two of this series. As a recap, in the last section we talked about webhooks, what are they, why use them and gave some real life examples.

I have decided to use a webhook-only app for this example because the setup is simple, and event subscriptions are all we'll need. You can also use webhooks with OAuth apps and the Server-to-Server OAuth apps if you need to make API requests.

Create a webhook-only app in the Zoom App Marketplace:

Log in to your Zoom account and head to the Zoom App Marketplace to start.
Click the dropdown that says Develop and then click Build App:

Make sure to click Create under the tile that says Webhook Only and give your app a name.

Fill up the required information and once that's done, head to the Feature tab and make sure to enable event subscriptions. Give your event subscription a name and in the event notification endpoint URL, make sure to add your ngrok URL. We need to expose the local server to the internet to accept post requests from Zoom.

To get an event notification endpoint URL for this guide, run the following command:

$ ngrok http 3000

Copy the ngrok https url displayed in terminal and include /webhook path, it should look like this:

https://exampleurl.ngrok.io/webhook

Click on Add events. For this guide, we will only add "Meeting has been created" and "Meeting has been deleted" and click done.

Lastly, click Continue so you can activate your app.

Set up the sample app

Pre-requisites:

Node JS
Ngrok
PostgreSQL
Zoom Account
Webhook-only app credentials

Now that your webhook-only app is created and activated in the Zoom Marketplace, it is time to run the sample app in your local environment.

Setup and install

First, clone the git repository found here:

git clone https://github.com/zoom/webhook-to-postgres

Use NPM to install dependencies:

$npm install

Open the .env file in your text editor and enter the following information from the feature section that you just configured:

# Zoom Secret token from your Webhook only app
ZOOM_WEBHOOK_SECRET_TOKEN=

Create our Database

You can skip these steps if you already have Postgres installed in your local environment. If not, follow along to install pg and create a table in your database.

If you are using Windows, download a Windows installer of PostgreSQL, or you can use this PostgreSQL Portable Copy.
If you are using a Mac and you have Homebrew installed on your computer, open up the terminal and install PostgreSQL with brew:

brew install postgresql

After the installation is complete, we'll want to get PostgreSQL up and running, which we can do with services start.

brew services start postgresql

With PostgreSQL now installed, we will connect to the default Postgres database running

psql postgres

We are now inside psql in the Postgres database. You will see the prompt ends with an # to denote that we are logged in as the superuser, or root (postgres=#).
Commands within psql start with a backslash. To test this, we can check what database, user, and port we have connected to using the \conninfo command

postgres=# \conninfo

Creating a role in Postgres

We are going to create a role called "me" and give it a password of "password":

postgres=# CREATE ROLE me WITH LOGIN PASSWORD 'password';

And we want "me" to be able to create a database:

postgres=# ALTER ROLE me CREATEDB;

Now, we will create a database for the "me" user. Exit from the default session with \q for quit and now we will connect Postgres with "me"

psql -d postgres -U me

We can create a database with the SQL command as follows:

CREATE DATABASE zoomwebhooks;

Connect to the new database

\c zoomwebhooks

You are now connected to database "zoomwebhooks" as a user "me".

Creating a table in Postgres

Finally, in the psql command prompt, we will create a table called events with four fields, two VARCHAR types, one BIGINT type, and an auto-incrementing PRIMARY KEY ID:

CREATE TABLE events (
  ID SERIAL PRIMARY KEY,
  name VARCHAR(30),
  accountid VARCHAR(30),
  meetingid BIGINT
);

We have finished with all our PostgreSQL tasks, and make sure to add the credentials in your .env file. Now it is time to get our app up and running!

# PostgreSQL credentials and information
PORT=
PG_USER=
PG_HOST=
PG_DATABASE=
PG_PASSWORD=
PG_PORT=

Start the app
It is time to run the app

$npm run start

While your app is running on port 3000, go to Zoom here and create a meeting or delete an existing meeting in your account.

Once you do this, you will see the event printed in your console and a new instance created in your Postgres database.

You can add as many events as you want, and they all will be stored in your database.

Thank you for follow along and happy coding 😀!

Sending webhooks to a postgres database

Elisa Levet — Thu, 15 Sep 2022 00:15:49 +0000

What are webhooks?

Webhooks are a powerful and valuable tool many Zoom developers use to build event triggers, automatically subscribe to data, and receive a high volume of data without needing to make API requests. To utilize them and accept the incoming requests, you'll need to setup a database, like PostgreSQL.

In this series, we will learn more about:

Webhooks: what are they, why use them, and the main difference between webhooks and API requests
Example of where Zoom's webhooks can be used vs. APIs requests
How to create an app in our Zoom Marketplace and enable event subscriptions
Set up our webhook sample app
Set up a Postgres database to receive and store Zoom events
Run our webhook sample app and start storing events in your database Let's get started!

What are webhooks?

Webhooks are automated event notification messages sent from one server to another in the form of HTTP requests.

Zoom uses webhooks to push the event-related data to your server for events your app has subscribed to. Webhook events (from Zoom) do not count toward API rate limits, making them a valuable tool for getting a large volume of data. Instead of requesting data through an API, your application tells Zoom to send data when the event happens.

Webhooks are almost always a faster method to automatically receive data rather than making API requests.

For a further overview of webhooks, our friends at ngrok have created a great resource explaining what webhooks are with a directory of providers.

But what is the difference between API calls and webhooks?

API calls work on request-based output mechanisms, and webhooks work on event-based output mechanisms.

Think about this real-life example:

⏰ Let's say that every night before you go to bed, you set up an alarm for 6:00am, and you know that this alarm will go off at 6:00am. Instead of waking up in the middle of the night multiple times to check the time (like an API call), you can just sleep tight knowing that an alarm will wake you up when it's time!

Now, let's translate this example to a specific Zoom scenario:

🏢 Let's say you work in a company with around 40 people under the same Zoom account, all who host daily meetings. You've just been tasked to get all the recordings from all the meetings held during the day under your company's Zoom account.

You could do it one of two ways. The first option is to call the recordings API to check if a meeting has ended and if it has a recording available (which, if you think about it, can be a lot because there might be at least 40 meetings to check daily). That's a lot of requests your app needs to make!

Instead, a second option would be to use event subscriptions in one of our various app types and wait for a near real-time notification of when the recordings are available. This means you won't have to continuously check if the meetings have ended or if they have recordings available.

Let's put it all into practice:

In the next series, we'll create a Webhook-only app in the Zoom App Marketplace and set up a Postgres database to receive the data.

For this guide, we will use a Webhook-only app as it is purely a subscription to webhooks, but you can also use webhooks with OAuth and Server-to-Server OAuth apps.

When to use Server-to-Server OAuth app and when to use OAuth app ?

Elisa Levet — Thu, 01 Sep 2022 17:26:10 +0000

If you are asking yourself should I use a Server-to-Server OAuth app or a “standard” OAuth app? 🤔

I would suggest you to start by asking yourself the following:

So, if you are planning on developing an app that is going be used by people you should definitely be looking into an OAuth app.

And what I mean by this is that if you want your application to make API calls to the Zoom endpoints on behalf of 3rd party users, you will need an OAuth app that the end user will authorize to grant your application permission to access their data.

Now, if your application is going to be used by programs and if it is going to make API calls on behalf of the account and has NO user interaction, then you are looking into a Server-to-Server OAuth app

Let’s put it in simple words now:

📝 Server-to-Server OAuth:

If your application calls the Zoom APIs on behalf of the account without users interaction
Internal applications that work with own data rather than a users data
Use cases: Internal reporting tools, Managing internal users, Managing accounts.

👥 OAuth app:

Applications created for 3rd party users
Applications authorized and used by people
Use cases: Scheduling apps, Tele-health apps, Learning Management system apps.

Learn more about the different app types available in the Zoom Marketplace here: https://marketplace.zoom.us/

For more questions about this topic, join us at the Zoom Developer Forum: https://devforum.zoom.us/

Happy coding! 😀

JWT app vs Server to Server OAuth app

Elisa Levet — Thu, 18 Aug 2022 18:15:00 +0000

With the Deprecation of the JWT app from the Marketplace next year, we have been encouraging developers to start migrating from their JWT app to the Server-to-Server OAuth app, which provides more granular scoping options for internal apps that retrieve data from our endpoints.

Now, what are the differences between JWT apps and Server-to-Server OAuth apps?

Internal JWT apps, created by account admins, have wide scope access.
Server-to-server OAuth allows individual users to create apps with scoped access to APIs which reflect the access they already have.
JWT apps rely on token generation using account credentials (API key and API secret)
Server-to-Server OAuth apps rely on requesting an access token to the Zoom OAuth endpoint using account credentials (Account ID, Client ID and Client Secret).
Access tokens generated with Server-to-Server OAuth app are *only valid for one hour *(a new one must be requested once they expired).

It is important to make emphasis on the fact that the only thing that changes with this migration is the way we are requesting an access token and making the API call will remain the same.

But how can you enable the Sever-to-Server OAuth app and how can you make sure that specific permissions are reflected on the app itself?

Once the app is enabled in the account (refer to this post if needed https://dev.to/zoom/why-use-server-to-server-oauth-1n53), it is important to define which permissions you want to grant to the developers that will have access to this type app, because the developer will only see the scopes that they can authorized.

For example, let’s say that you do not want your developer to have access to the Dashboard, so you have to make sure that in the Roles setting for that developer those features are disabled:
(ADMIN > User Management > Roles > Edit)

What this will ensure is that Dashboard scopes wont be visible or available in the developer’s Server-to-Server app

Here are some code snippets that demonstrate the generation of access token using JWT apps and the request of access token using Server-to-Server OAuth app:

Using JWT app credentials to generate an Access token, then use it to make an API call to our Get Users endpoint

Using Server-to-Server OAuth app credentials to request an access token to the Zoom OAuth endpoint, then use it to make an API call to the same Get Users endpoint

It is important to note that once your access token expires, you just need to make the same request to the Zoom OAuth endpoint to generate a new one (there is no refresh token involved); but the generation of a new token,** invalidates the previous one **(even if it was not expired).

Thank you so much for reading me and happy coding!

Why use Server To Server OAuth?

Elisa Levet — Fri, 15 Jul 2022 16:01:41 +0000

The JWT app type will be deprecated in June 2023 and we recommend and highly encourage that you start migrating from the JWT app to the newly introduced Server-to-Server OAuth App.

**But, you might be wondering why we are deprecating the JWT app?**

The main reason we are introducing server-to-server OAuth over JWT is to provide more granular scoping options for internal apps that retrieve data from our endpoints.

Internal JWT apps, created by account admins, have wide scope access and rely on token generation from account-level credentials. Server-to-server OAuth allows individual users to create apps with scoped access to APIs which reflect the access they already have.

Learn more about the Frequent Asked Question here:
https://marketplace.zoom.us/docs/guides/build/jwt-app/jwt-faq/

That being said, here is a quick and simple guide on how to use or new app with Postman:

This new app type facilitates OAuth-authenticated requests between servers without end-user involvement. This grant type enables your private server application to get your account owner access token without user interaction.

To start using this App, the Administrator for your Zoom account or the Owner of the account must enable the view and edit permissions for Server-to-Server OAuth app by going to User Management > Roles > Role Settings > Advanced features.

Once those permissions are enabled, you will be able to see the app in your Marketplace Dashboard.

Once the app is created and you have added the scopes and features (event subscriptions) that you want to include, you can go ahead and activate your app in your account.

Feel free to follow along on the Steps on How to Create a Server-to-Server OAuth app here:

https://marketplace.zoom.us/docs/guides/build/server-to-server-oauth-app/#create-a-server-to-server-oauth-app

Now, it is time to get started and use Postman with our newly created app.

Step 1

Create a new Post request to https://zoom.us/oauth/token

Step 2

Add the following Query Params
grant_type=account_credentials
account_id={account_id}

(Grab your account_id from the App credentials Tab in your newly created app)

So your Post request should look something like this:

Step 3

Go to the Authorization Tab and select Basic Auth as the authorization type and user your Client ID as a Username and your Client SECRET as your password:
(Grab those credentials from your newly created app as well)

Once that is all done, you should be able to send the POST request and you will get a response that will look something like this:

You should be able to use the access_token as a bearer token to make API calls to those endpoints that can be accessed with the scope/s set up in the Server-to-Server application.

Hope this helps to understand this new app type better and let me know if you have any questions or suggestions!

Happy coding!
Elisa :)