KJEmpireCalz Integration Docs
Empire-wide self-hosted booking infrastructure built on Cal.com. Drop the integration kit into any KJE product in under an hour.
v1.0 — Empire Infra
Empire-wide self-hosted booking infrastructure built on Cal.com. Drop the integration kit into any KJE product in under an hour.
v1.0 — Empire InfraIntegration contract
Every empire product follows the same integration path. Nothing custom — just drop in the kit and configure.
Clone the integration-kit/ directory from /opt/empirecal/ into your product repo. No submodule — a flat copy per product.
In your Cal.com event type, enable Webhook → Subscribe to events. Copy CALCOM_WEBHOOK_SECRET from Brain vault (kj_empirecalz) into your product environment. The kit verifies HMAC-SHA256 on every payload.
Wire your app server to call handle_cal_webhook (Python) or handleCalWebhook (TypeScript) for incoming POST requests to /webhooks/cal. The kit parses, verifies, and dispatches to event handlers automatically.
Edit webhook-handler.py or webhook-handler.ts — four event handlers are pre-wired. Add your DB writes, email sends, and CRM updates per event. Payments stub is already in place (see KJEmpirePayz section below).
Drop the <script> tag from embed-snippet.html anywhere you need a booking button or inline widget. Theming is pre-set to match the KJE dark cyberpunk palette.
Webhook events
Every integration kit handler responds to these four Cal.com webhook events. No-ops for unused events are fine.
| Event | When it fires | Standard response |
|---|---|---|
| BOOKING_CREATED | New booking confirmed by attendee | Insert DB row, send confirmation email, route payment via KJEmpirePayz |
| BOOKING_RESCHEDULED | Existing booking moved to a new time | Update DB row, send reschedule notification |
| BOOKING_CANCELLED | Booking cancelled by host or attendee | Soft-delete DB row, send cancellation email, route refund via KJEmpirePayz |
| MEETING_ENDED | Video meeting recording completed | Store recording URL, trigger follow-up sequence, update CRM |
Kit contents
8 drop-in files. Copy the whole directory — nothing requires modification before it runs.
Python FastAPI handler with HMAC-SHA256 verification and 4 event dispatchers.
TypeScript/Node equivalent for Express or Next.js API routes.
Drop-in Cal.com embed with KJE dark theme overrides and booking URL config.
Supabase-compatible table definitions: bookings, attendees, events.
Branded booking confirmation email — gold + cyan on dark background.
Reschedule notification email with updated time and calendar link.
Cancellation email with optional refund status line.
Quick-start guide, env vars reference, event contract, and deployment notes.
Payments
All payment flows (charges, refunds, subscriptions) are centralized through KJEmpirePayz — the empire-wide Stripe integration. Do not wire Stripe directly in product handlers.
Never set STRIPE_API_KEY or STRIPE_WEBHOOK_SECRET in a product .env. All Stripe credentials live in KJEmpirePayz only. Products call KJEmpirePayz endpoints — they never call Stripe directly.
The integration kit ships with handle_payment_via_kjempirez() (Python) and handlePaymentViaKJEmpirePayz() (TypeScript) stub functions. They log the event and return. When KJEmpirePayz ships, swap the stub call for the KJEmpirePayz SDK call — no other handler changes needed.
Infrastructure
All empire products point bookings at the central Cal.com instance:
https://book.empirecalz.com
Configure Cal.com to POST webhook events to your product endpoint. The kit handler expects:
POST /webhooks/cal Headers: Content-Type: application/json X-Cal-Signature-256: t=<timestamp>,v1=<hmac>
The booking host runs 24/7 with nightly R2 backups (03:15 UTC, 14-day retention). TLS via Let’s Encrypt auto-renews. Infrastructure: RackNerd VPS + Caddy 2.6.
Configuration
Add these to your product environment. Retrieve secrets from Brain vault under kj_empirecalz.
| Variable | Value / Source | Required |
|---|---|---|
| CALCOM_WEBHOOK_SECRET | Brain vault: kj_empirecalz / CALCOM_WEBHOOK_SECRET |
Yes |
| CALCOM_BOOKING_URL | https://book.empirecalz.com |
Yes |
| CALCOM_API_KEY | Brain vault: kj_empirecalz / CALCOM_API_KEY |
If using API |
| STRIPE_* | Do not set — use KJEmpirePayz instead | Never |