Enabling Event Subscriptions Programmatically

API and Webhooks
,
1

Zoom offers a set of endpoints to help developers programmatically enable event subscriptions. One key application of these endpoints is consolidating different regional instances into a single app, allowing developers to rely on the customer’s instance instead of setting up a global webhook.

Another use case is giving developers precise control over which users or accounts they need to receive events for, allowing developers to programmatically tailor event subscriptions in their applications.

Available Endpoint for Managing Event Subscriptions

  1. Create an event subscription
  2. Subscribe to an event subscription
  3. Unsubscribe from an event subscription
  4. Delete an event subscription
  5. Get user or account event subscriptions

Important considerations when using these endpoints:

  • Developers do not need to configure/add these webhook events manually within the build flow.
  • The required scopes to use this set of endpoints, do not need to be manually selected during the app build process
  • The required scopes for the events that the app wants to receive when programmatically creating the subscription must be selected within the build flow.
  • Webhook subscriptions are app-owned resources, meaning access must be granted via a Client Credentials token for General Oauth apps, and for Server to Server Oauth apps

Obtaining an Access Token Using Client Credentials Grant for General app type and Server to Server OAuth app

To enable event subscriptions using a General app type, developers must obtain an access token via the Client Credentials Grant. This token is required to authenticate requests to the relevant endpoints.

Retrieving an access token

Use the following cURL command to obtain an access toke:

curl --location --request POST 'https://zoom.us/oauth/token?grant_type=client_credentials' \
--header 'Authorization: Basic <YOUR_BASE64_ENCODED_CREDENTIALS>'

The expected response from the previous request should look something like this:

{
    "access_token": "eyJzNjMxYWQ0MTRiMiJ9.eyJhdWQiOiJodHRwczovL29hdXRoLnpvb20udXMiLCJ1aWQiOiI2R3RkaGVaUVNxLWwySmxGVzZ2TEZ3IiwidmVyIjoxMCwiYXVpZCI6IjZmOWE4ZjIyMTg2NjdmMzczMmFiM2JmMWYzNDQwMjAxODE3NDk2YjI4ZDdiZDhkOTQzOWI1MDAxNWFiNmE1YTAiLCJuYmYiOjE3NDA0MjEzMTcsImlzcyI6InptOmNpZDpScVRwYWJXelFReXRWbFZzVUpINjZ3IiwiZ25vIjowLCJleHAiOjE3NDA0MjQ5MTcsInR5cGUiOjIsImlhdCI6MTc0MDQyMTMxN30.I2VRTjoQsYTNhIT_106eEK3dquTjMyGsKJvWXM3fBW3WCQu0jD1YofRQDIqUIQvDZ7PmuArS-SYf5zUZUgLdOA",
    "token_type": "bearer",
    "expires_in": 3600,
    "scope": "marketplace:delete:event_subscription marketplace:read:list_event_subscriptions marketplace:update:event_subscription marketplace:write:event_subscription marketplace:write:websocket_connection",
    "api_url": "https://api.zoom.us"
}

Note that this request returns an access token that includes the necessary scopes for managing webhook subscriptions. This token must be used as the Authorization token for subsequent API calls.

Sample workflow:

  1. After generating an access token, the first endpoint you will need to call is the Create an event subscription to create/generate an event subscription and get a subscription ID

Request:

curl --request POST \
  --url https://api.zoom.us/v2/marketplace/app/event_subscription \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "events": [
    "meeting.created"
  ],
  "event_subscription_name": "Example Event Subscription",
  "event_webhook_url": "https://www.example.com",
  "user_ids": [
    "_8KG7DeoRU2xIsDSY9ed2Q,90KG7DeoRU2xIsDSY9edwe"
  ],
  "subscription_scope": "user",
  "account_id": "pvg3UAgpRlyTDW-9sIpKcw"
}'

Response:

{
  "event_subscription_id": "0ZAaJY4dQ52BbwI9PArBLQ"
}
  1. Once you have an event_subscription_id from the newly created event subscription, you will need to use the subsequent endpoint to subscribe to that event subscription, using the Subscribe to an Event Subscription endpoint

Request:

curl --request PATCH \
--url https://api.zoom.us/v2/marketplace/app/event_subscription/0ZAaJY4dQ52BbwI9PArBLQ \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"user_ids": [
"_8KG7DeoRU2xIsDSY9ed2Q,90KG7DeoRU2xIsDSY9edwe"
],
"account_id": "5AATFjiUS0yEnELIMzQO4g"
}'

Response:

200 OK

  1. You can also unsubscribe from the event subscription using the Unsubscribe from an Event Subscription endpoint using the event_subscription_id

Request:

curl --request DELETE \
--url 'https://api.zoom.us/v2/marketplace/app/event_subscription?event_subscription_id=sFrBezKES3-UdcfMPXFA0A&account_id=pvg3UAgpRlyTDW-9sIpKcw' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Response:

200 OK

  1. Lastly, you can delete the event subscription from the app using the Delete an Event Subscription endpoint after you unsubscribe from it

Request:

curl --request DELETE \
--url https://api.zoom.us/v2/marketplace/app/event_subscription/0ZAaJY4dQ52BbwI9PArBLQ \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Response:

200 OK

  1. We also offer an endpoint to Get User or Account Event Subscriptions

Request:

curl --request GET \
--url 'https://api.zoom.us/v2/marketplace/app/event_subscription?user_id=3W35hpuuRqeuC8U8Jx8w7A&account_id=pvg3UAgpRlyTDW-9sIpKcw' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Response:

{
"next_page_token": "eer587w4eiyfsudgf",
"page_size": 30,
"event_subscriptions": [
{
"event_subscription_id": "sFrBezKES3-UdcfMPXFA0A",
"events": [
"meeting.deleted"
],
"event_subscription_name": "Example Event Subscription",
"event_webhook_url": "https://www.example.com",
"subscription_scope": "user",
"created_source": "default",
"subscriber_id": "5AATFjiUS0yEnELIMzQO4g"
}
]
}

Notes:

  • These API calls require the Client Credentials token or Account Credentials token obtained in the previous step.
  • Be sure to replace {eventSubscriptionId} with the actual subscription ID when making requests to specific subscriptions.
  • If you are adding an event that requires a new scope in the build flow, the app will need to obtain the necessary scopes from users. Failing to do so will result in a failed request when creating the event subscription.

Happy coding!

1 Like