Webhooks
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. The account must install your webhook-enabled app to authorize data flow via webhooks.
These event notifications are sent as HTTP POST
requests in JSON, to the endpoint you specify in your Marketplace app.
Objects, Actions, and Events
Objects are pieces of data that form the resources provided by Zoom such as Zoom APIs and Webhooks. An event occurs when a user performs an action that causes a change in the value of an object. The events are grouped into core event types as listed below:
- Meeting Events
- Webinar Events
- Recording Events
- Zoom Room Events
- User Events
- Account Events
Each Zoom event type is comprised of multiple webhook events. These webhook events are defined by a common naming rule: $object.$action
. The following table represents a list of objects and actions that make up Zoom events:
Objects |
|
---|---|
Actions |
|
For example, one of the webhook events under the User event type is user.created
. This webhook is triggered whenever a user is created on a Zoom account that is subscribed to the User has been created
event under the User
event type.
To enable webhooks for these events, you must add Event Subscriptions to your Marketplace app. Refer to the next section, Enable Webhooks, for information on enabling webhooks with event subscriptions for each app type.
Enable Webhooks
Webhooks can be enabled in any of the following app types in the Zoom App Marketplace:
-
OAuth App: Select this app type to securely integrate with Zoom APIs and access users’ authorized data using a user-based authentication approach. This app can either be installed and managed across an account by account admins (account-level app) or by users individually (user-managed app). You can also publish this app on the Zoom App Marketplace and make your app accessible to millions of Zoom users.
-
JWT App: Select this app type to establish server-to-server interactions with the Zoom API.
-
Webhook-only App: Select this app type if your app requires user information only on events that you subscribe to and does not need to pull data from the Zoom APIs. This app will only be activated in your Zoom account and thus, you can subscribe to events that occur in your Zoom account only.
-
Chatbot: Select this app type to enable your app to interact with Zoom users on the Zoom Client via chat. You can subscribe to events that occur on your own account or any other accounts that install your Chatbot.
To enable webhooks, in all of these apps, you must follow the following steps at a minimum:
-
Create an app on the Zoom App Marketplace. Choose one of the app types mentioned above. Provide basic information required while creating the app.
-
Provide a valid Event Notification Endpoint URL. This is the designated URL of your app where you will receive the webhook POST requests, also known as event notifications.
The notifications will be sent every time an event that your app is subscribed to, occurs in a Zoom account of a user that has installed your webhook-enabled app. This URL must be secured over HTTPS. -
On the Features page of the App’s Dashboard, enable Event Subscriptions. Select the events from available Event Types that you would like to subscribe to and click “Done”. Save the configurations for the Event Subscriptions.
To add additional Event Subscriptions, click + Add new event subscription again. Although you can subscribe to as many events as needed for each event subscription, you can only have a maximum of ten event subscriptions per app.
Event Subscriptions can have duplicate Events. For example, one Event Subscription could have Meetings and User Events, and a second Event Subscription can have Meetings and Recordings events.
Optionally, you can customize other features that are available for your app such as Scopes, Chat Subscription, etc. as needed.
Notification Structure
After one of the events that you subscribed to occurs on your Zoom account or any other Zoom account that has installed your webhook-enabled app, Zoom will send an event notification to your app’s Event Notification Endpoint URL in the form of an HTTP POST request. This request includes a JSON Request Body and multiple Headers.
Headers
The POST request will contain several headers such as content-type
and authorization
. The content-type
header represents the media type of the resource whereas the authorization
header is unique to your app and confirms the validity of the request. To verify if a request is sent by the Zoom Service, compare the authorization
header with the verification token generated in the Features page of your Marketplace app.
Request Body
The request body includes information on the event such as the type of event that occurred, the account_id
(a unique identifier for a Zoom account) of the account in which the event occurred, and information on the object containing fields whose value(s) have changed during an event.
IP Addresses
We strongly recommend that you use verification token to verify whether or not the event notifications that you receive are originating from Zoom. We do not recommend whitelisting by IP addresses as we might make updates to the IP ranges that we use, however, if needed, you can refer to the following list for IP addresses that Zoom may use to send event notifications:
18.205.93.128/25
52.202.62.192/26
3.80.20.128/25
3.208.72.0/25
3.211.241.0/25
3.235.69.0/25 (3.235.69.0 - 3.235.69.127)
3.235.71.128/25 (3.235.71.128 - 3.235.71.255)
3.235.72.128/25 (3.235.72.128 - 3.235.72.255)
3.235.73.0/25 (3.235.73.0 - 3.235.73.127)
3.235.96.0/23
52.61.100.254
52.61.100.253
34.236.0.178
18.212.92.53
54.242.40.107
34.229.215.16
54.225.152.106
54.91.231.136
18.235.142.226
50.17.42.214
35.175.188.98
50.19.221.116
34.228.32.3
54.157.245.241
Notification Delivery
After receiving a notification, your Event Notification Endpoint URL should respond with either a 200
or a 204
HTTP status code within three seconds for Zoom to consider that the notification was successfully delivered. Zoom will try to deliver the notification for up to three times. The first retry will be sent 5 minutes after the initial notification delivery attempt, second retry will be sent 20 minutes after the first retry attempt and third retry will be sent 60 minutes after the second retry attempt for an event. If a 2XX
response is received after one of these attempted retries, the event notification will continue to be sent as usual. However, if Zoom doesn’t receive a 2XX
response even after executing all three retries, no further notifications related to that event will be sent to your app’s Event Notification Endpoint URL.
Delivery latency
The event_ts
parameter is included in the payload of all event notifications. This field represents the timestamp for when the associated event occurred. If you keep track of notification delivery timestamp in your application, you can determine the latency in webhook delivery by calculating the difference between the delivery timestamp and the value of the event_ts
parameter.
Next Steps
Explore various Zoom Webhooks, learn about their payloads and view examples in the upcoming sections. Or head over to the Automate Workflows With Zoom Webhooks blog for a quick walkthrough.
Feeling ready to enable webhooks in your app? Start building on the Zoom App Marketplace.
Need Support?
The first place to look for help is on our Developer Forum, where Zoom Marketplace Developers can ask questions for public answers.
If you can’t find the answer in the Developer Forum or your request requires sensitive information to be relayed, please email us at developersupport@zoom.us.