Apps Overview
Purpose and Scope
Apps are the integration layer that lets a self-hosted Cal.diy instance connect scheduling workflows to external systems such as calendars, identity providers, payment processors, and meeting tools. For operators, the main job is not writing integration code on day one; it is registering credentials with each provider, placing the resulting secrets in the correct environment files, configuring OAuth callback URLs that point back to the deployed Cal.diy URL, and refreshing the app store where required. The first-party docs present Apps as a getting-started destination from the self-hosting index, alongside installation, migrations, Docker, and upgrades, so this page treats app setup as an operational part of running the instance rather than an optional afterthought.
Sources: apps/docs/content/index.mdx, apps/docs/content/apps/google.mdx, apps/docs/content/apps/microsoft.mdx, apps/docs/content/apps/stripe.mdx
Cal.diy is explicitly positioned as the community self-hosted edition and carries a strong personal, non-production recommendation in the documentation index. That context matters for integrations because app credentials usually grant access to sensitive third-party data: calendars can reveal availability and event metadata, payment webhooks can carry financial events, and OAuth clients can be scoped incorrectly if redirect URLs or app types are wrong. Treat each app setup as part of your deployment security boundary. Before enabling integrations, confirm that your public application URL, HTTPS setup, database, and environment management practices are stable enough to protect provider secrets and callback traffic.
Sources: apps/docs/content/index.mdx
Relevant Source Files
apps/docs/content/index.mdx- Defines the self-hosting documentation entrypoint, warns about the intended Cal.diy usage model, and links Apps from the Getting Started section.apps/docs/content/apps/google.mdx- Documents Google Calendar credential creation, OAuth consent configuration, redirect URIs, environment variables, and app-store reseeding.apps/docs/content/apps/microsoft.mdx- Documents Microsoft Graph app registration, the Office 365 calendar callback URL, and the required client ID and secret environment variables.apps/docs/content/apps/stripe.mdx- Documents Stripe payment setup, public and private keys, Connect OAuth, callback and webhook URLs, webhook event selection, and webhook secret storage.packages/app-store/package.json- Declares the@calcom/app-storepackage surface, workspace dependencies, peer dependencies, and package scripts used by the integration package.
Integration Categories
Calendar integrations are the first category most self-hosters configure because they determine whether Cal.diy can read availability and write booking events into the user’s external calendar. The Google page walks through enabling the Google Calendar API, configuring an OAuth consent screen, adding calendar scopes, creating a Web Application OAuth client, and registering both the Google Calendar integration callback and Google auth callback. It also requires the downloaded OAuth client JSON to be stored under GOOGLE_API_CREDENTIALS in both .env and .env.appStore, then sets GOOGLE_LOGIN_ENABLED=false to keep the Google integration internal for the self-hosted app configuration.
Sources: apps/docs/content/apps/google.mdx
Microsoft calendar setup follows the same broad OAuth pattern but uses Azure App Registration and Microsoft Graph terminology. The documented application type is a multitenant registration, and the web redirect URI points to the Office 365 calendar integration callback. Instead of a JSON credential blob, the Microsoft setup uses two discrete environment variables: MS_GRAPH_CLIENT_ID and MS_GRAPH_CLIENT_SECRET. This difference is important when you build deployment automation. Google credentials are copied as an entire JSON string, while Microsoft credentials are copied as a client identifier and generated secret value from the Azure portal.
Sources: apps/docs/content/apps/microsoft.mdx
Payment integrations form a second category because they require both outbound OAuth configuration and inbound webhook processing. The Stripe guide starts with API keys, maps the publishable token to NEXT_PUBLIC_STRIPE_PUBLIC_KEY, maps the secret token to STRIPE_PRIVATE_KEY, and then enables OAuth for Standard Accounts in Stripe Connect. The callback URL ends in /api/integrations/stripepayment/callback, while webhook delivery is configured separately at /api/integrations/stripepayment/webhook. The webhook must include all payment_intent and setup_intent events, and the generated whsec_... secret is stored as STRIPE_WEBHOOK_SECRET.
Sources: apps/docs/content/apps/stripe.mdx
Video and shared app infrastructure appear in the package layer even when this overview’s provider setup snippets focus on calendars and payments. The @calcom/app-store package depends on workspace packages for Daily video, Office 365 video, Zoom video, features, i18n, lib, dayjs, and UI. It also declares peer dependencies on React, React DOM, Stripe, and Zod. That manifest shows that app-store code sits between provider-specific packages and shared Cal.diy primitives: UI components render the app experience, i18n supports labels and copy, feature packages provide higher-level behavior, and provider packages supply concrete integration implementations.
Sources: packages/app-store/package.json
System-to-Code Mapping
| Concern | Setup evidence | Runtime/package evidence |
|---|---|---|
| Documentation entrypoint | apps/docs/content/index.mdx links Apps from Getting Started | App setup is part of the self-hosting operator workflow |
| Google Calendar | apps/docs/content/apps/google.mdx | App-store reseeding is required after adding credentials |
| Microsoft Calendar | apps/docs/content/apps/microsoft.mdx | Uses Microsoft Graph credentials for Office 365 calendar callback |
| Stripe Payments | apps/docs/content/apps/stripe.mdx | @calcom/app-store peers on stripe for payment integration code |
| Shared integration package | Provider docs plus packages/app-store/package.json | @calcom/app-store ties providers to shared workspace packages |
The operating model is consistent across providers. Start in the external provider console, create or register an application, choose a web application or server-side OAuth style where required, and then add callback URLs that point to your Cal.diy deployment. Next, copy provider-generated credentials into the self-hosted environment files using the exact variable names from the relevant app page. Finally, run any Cal.diy-side refresh step documented for that provider, such as Google Calendar’s pnpm db-seed, so the app store data reflects the integration you just configured.
Sources: apps/docs/content/apps/google.mdx, apps/docs/content/apps/microsoft.mdx, apps/docs/content/apps/stripe.mdx
Setup Flow for Operators
Use one canonical application URL when configuring integrations. Each provider page uses <Cal.diy URL> as the placeholder for redirect and webhook endpoints, so mismatches between local, staging, and production URLs are a common source of confusing OAuth failures. For a local test instance, the callback URL must point to the URL that the provider can actually redirect to during your test. For a deployed instance, update credentials any time the public hostname, protocol, or reverse proxy routing changes. Payment webhooks are especially sensitive because Stripe sends events independently of a browser session.
Sources: apps/docs/content/apps/google.mdx, apps/docs/content/apps/microsoft.mdx, apps/docs/content/apps/stripe.mdx
A practical setup sequence is to enable calendar integrations before payment integrations. Calendars validate the core scheduling loop: users can connect a provider, Cal.diy can request the needed scopes, and bookings can land on the external calendar. After that path is stable, configure Stripe so paid event types can receive payment and setup-intent events. Keep .env and .env.appStore in sync where a provider requires both, and remember that provider consoles may show client secrets only once. Store secrets in the same secret-management path you use for the rest of the self-hosted deployment.
Sources: apps/docs/content/apps/google.mdx, apps/docs/content/apps/stripe.mdx
Compact Reference
| Provider | Category | Required values or actions | Callback or webhook paths |
|---|---|---|---|
| Google Calendar | Calendar and optional auth-related setup | GOOGLE_API_CREDENTIALS in .env and .env.appStore; GOOGLE_LOGIN_ENABLED=false; run pnpm db-seed after credentials are added | /api/integrations/googlecalendar/callback, /api/auth/callback/google |
| Microsoft / Office 365 Calendar | Calendar | MS_GRAPH_CLIENT_ID, MS_GRAPH_CLIENT_SECRET | /api/integrations/office365calendar/callback |
| Stripe | Payments | NEXT_PUBLIC_STRIPE_PUBLIC_KEY, STRIPE_PRIVATE_KEY, STRIPE_CLIENT_ID, STRIPE_WEBHOOK_SECRET; select payment_intent and setup_intent webhook events | /api/integrations/stripepayment/callback, /api/integrations/stripepayment/webhook |
The app-store package itself is private and exposes ./index.ts as its main entry. Its scripts are mostly quality and type-safety oriented: build:types, type-check, type-check:ci, lint, lint:fix, and lint:report. For maintainers, that means provider setup documentation and runtime package work are related but not identical tasks. Operators follow the docs pages to supply credentials and callbacks. Contributors working on app-store internals use the package scripts and workspace dependencies to keep integration code type-checked, linted, and aligned with shared Cal.diy packages.
Sources: packages/app-store/package.json
Next Steps
After reading this overview, configure one provider at a time and verify it end to end before adding the next. Start with Google Calendar or Microsoft Calendar if your goal is availability and booking synchronization. Move to Stripe only after your deployment URL is stable and reachable by external webhook delivery. If a provider is visible in the app store but does not work, re-check the environment variable names, redirect URL spelling, and whether the app-store data needs to be reseeded. For deeper setup details, continue to the provider-specific pages rather than relying on this overview as a replacement.
Sources: apps/docs/content/apps/google.mdx, apps/docs/content/apps/microsoft.mdx, apps/docs/content/apps/stripe.mdx