We're currently utilizing the V1 webhook API without specifying any organization URI. If we opt to transition to the V2 webhook API to leverage its latest features, what changes should we anticipate? Would it be necessary to create an organization account, and if so, what would be the process for assigning existing users to the organization?
Answer
Migration to Calendly Webhook API V2 and Integration with Organization Accounts
Best answer by Austin
Hey
An organization is just a part of our account hierarchy, and even single user accounts will have an organization, where the single user is the organization owner. Using just a personal access token, any user can call the get current user endpoint here in order to find your specific organization URI (it’ll be found as the current_organization string).
In the V2 webhook subscription you must define the intake URL, events to subscribe to, your organization URI, user URI, and scope to created a new webhook subscription. Your scope can either be the user who is creating the webhook subscription using their credentials, or an organization if the personal access token is associated with an Owner/Admin in Calendly. You cannot however scope your subscription to a specific user other yourself (or the credentials you are using to create the subscription).
Another key change to the webhook subscription is our move to URI structure for our payloads. So you may need to build in some time to configure your gateway or any code you’ve created for the V1 webhooks as you make that change.
I hope that helps! Happy scheduling! 🙂
Make sure to review the V2 webhook payload specifications in the API docs at https://developer.calendly.com to make sure your application can handle them.
It’s not necessary to have an Organization account to use webhooks. Many endpoints can be scoped to either org or user. Individual users have their own organization too which you can fetch using the /users/{uuid} or /users/me endpoint.
Thanks for your response, @mattmanning. However, when I checked the documentation for webhook subscription, I noticed that the organization field is marked as mandatory.
https://developer.calendly.com/api-docs/c1ddc06ce1f1b-create-webhook-subscription
Hey
An organization is just a part of our account hierarchy, and even single user accounts will have an organization, where the single user is the organization owner. Using just a personal access token, any user can call the get current user endpoint here in order to find your specific organization URI (it’ll be found as the current_organization string).
In the V2 webhook subscription you must define the intake URL, events to subscribe to, your organization URI, user URI, and scope to created a new webhook subscription. Your scope can either be the user who is creating the webhook subscription using their credentials, or an organization if the personal access token is associated with an Owner/Admin in Calendly. You cannot however scope your subscription to a specific user other yourself (or the credentials you are using to create the subscription).
Another key change to the webhook subscription is our move to URI structure for our payloads. So you may need to build in some time to configure your gateway or any code you’ve created for the V1 webhooks as you make that change.
I hope that helps! Happy scheduling! 🙂
Hey Austin, thanks for the clarification! Your insights are really helpful, I appreciate it. Thank you so much!👍
Hi, I need another clarification. We are using personal access tokens (PATs) for the API calls. PATs do not expire, correct? If we opt for OAuth, then only the refresh token is required, correct? We have existing users with PATs. When I use those PATs with the V2 API, I get an "Unauthenticated - The access token is invalid" error. I also generated new PATs and tried to use them with V2, but encountered the same error. PATs created recently for new users work fine with the V2 API. I want to know how we can migrate old users to use the new API V2.
Hey
Are you generating V2 PAT towards the top of the page, or are you testing tokens generated towards the bottom of the page like you can see in my screenshot below?
Sign up
Already have an account? Login
Not a Calendly user yet? Head on over to Calendly.com to get started before logging into the community.
Employee Login Customer LoginLogin to the community
Not a Calendly user yet? Head on over to Calendly.com to get started before logging into the community.
Employee Login Customer LoginEnter your E-mail address. We'll send you an e-mail with instructions to reset your password.