Calendly

Two-way interview scheduling reconciliation, webhook event handling, and automated appointment tracking.

Overview

Calendly is the world's most popular automated scheduling platform for recruiter screen calls and interview rounds. Applivo integrates with Calendly via OAuth 2.0 and real-time webhook subscriptions (app/services/integrations/calendly.py) to automatically record interview appointments, reconcile candidate bookings, and handle cancellations without manual data entry.

Configuration

Connecting Calendly establishes OAuth authentication and registers a secure webhook subscription:

Open Dashboard → Connections.
Locate Calendly under Calendar and scheduling.
Click Connect. You are redirected to Calendly's official OAuth authorization page.
Authorize Applivo to read your user profile and manage webhooks.
Upon callback, Applivo securely registers an invitee.created and invitee.canceled webhook subscription with Calendly.
The connection turns Active, displaying your Calendly scheduling URL and user handle.

How it works

When a recruiter books or reschedules an interview through your Calendly link:

1. Webhook Dispatch: Calendly emits a signed JSON webhook payload to POST /api/integrations/calendly/webhook.
2. Cryptographic Verification: Applivo verifies the Calendly-Webhook-Signature header using HMAC-SHA256 and validates the timestamp within a 5-minute tolerance window to prevent replay attacks.
3. Account Resolution: Maps the subscription URI or candidate email to your user account.
4. Idempotent Matching: Matches the meeting to existing applications using external_id deduplication (interviews.external_id). If title overlap >= 0.6 or booking date is within +-2 days of an active application, it auto-assigns the interview record.
5. Ambiguous Resolution: If multiple applications match, the appointment is placed in a Pending Matches queue (GET /api/integrations/calendly/pending-matches) for your one-click manual confirmation.
6. Cancellation Handling: If the recruiter cancels, the webhook updates the interview record with outcome='cancelled'.

Available features

Automatic interview record creation on invitee.created events.
Cancellation tracking automatically updating interview outcomes.
Reconciliation engine matching recruiter bookings to target applications.
Pending match review modal for resolving ambiguous appointments.
Automatic deletion of Calendly webhook subscriptions upon disconnecting.

Permissions and data access

Requests standard Calendly OAuth scopes for user identity and webhook subscription management. Tokens are stored encrypted with AES-256-GCM.

Troubleshooting

Symptom	Likely Cause	Resolution
Webhook returns 401 Signature Verification Failed	CALENDLY_WEBHOOK_SIGNING_KEY mismatch or clock drift > 5 min	Verify signing key in server .env and ensure server clock is NTP synchronized.
Interview appears in 'Pending Matches'	Booking details did not decisively match a single company application	Open Connections → Calendly → Pending Matches and click Assign to link it to the correct job.

Frequently asked questions

What happens if a recruiter cancels the interview?

Calendly sends an invitee.canceled webhook. Applivo updates the interview record to 'cancelled' and notifies you via Slack or Telegram if enabled.