Bu rehberde: Cal.com hesabınızı bir API anahtarıyla bağlarsınız. OrqLabs imzalı bir webhook kurar; biri randevu aldığında, randevuyu ertelediğinde veya iptal ettiğinde iş akışınız başlar. Cal.com kutusuyla etkinlik türlerinizi ve randevularınızı okursunuz.
⏱ 5 dakika
Kimlik kartı
| Alan | Değer |
|---|---|
| Sağlayıcı anahtarı | CAL_COM |
| Kategori | Randevu |
| Kimlik doğrulama | API anahtarı (cal_live_…, Authorization: Bearer …), Cal.com API v2 |
| Kapsam | Proje bazlı |
| Webhook | Evet – bağlarken otomatik kurulur, imzalıdır (x-cal-signature-256) |
| Kutu | Cal.com (app.calCom) |
| Tetikleyiciler | Entegrasyon olayı → CAL_COM · New booking, CAL_COM · Booking rescheduled, CAL_COM · Booking cancelled |
Ne işe yarar?
Tetikleyiciler:
- New booking (
BOOKING_CREATED) – yeni randevu. Onay gerektiren türlerde randevu onaylandığında gelir. - Booking rescheduled (
BOOKING_RESCHEDULED) – randevu yeni bir saate taşındı; öğe yeni saati,previousBookingIdvepreviousStartTimealanları eski randevuyu taşır. - Booking cancelled (
BOOKING_CANCELLED) – katılımcı veya siz iptal ettiniz.
İlk öğenin alanları:
| Alan | Açıklama |
|---|---|
bookingId, bookingNumber | Randevu kimliği (uid) ve numarası (aynı olay iki kez gelirse ikincisi atlanır) |
name, email, phone, timezone | Katılımcı (ilk katılımcı) |
eventName, eventType, eventTypeId, title | Etkinlik türünün adı, kısa adı ve randevu başlığı |
startTime, endTime | Başlangıç / bitiş (ISO, UTC) |
location, meetingUrl | Konum (ör. integrations:daily, adres, telefon) ve görüntülü görüşme bağlantısı |
status | ACCEPTED, CANCELLED … |
organizerName, organizerEmail | Toplantı sahibi |
answers | Rezervasyon formu: { "Name": …, "Email address": …, "Additional notes": …, "Sorunuz": … } |
rescheduleUrl, cancelUrl | Katılımcıya gönderebileceğiniz yeniden planlama ve iptal bağlantıları |
cancelReason, canceledBy | İptal nedeni ve iptal eden |
rescheduleReason, previousBookingId, previousStartTime | Yeniden planlama bilgisi |
Cal.com kutusunun işlemleri:
| İşlem | Ne yapar | Etki |
|---|---|---|
| List event types | Etkinlik türlerinizi (kimlik, başlık, kısa ad, süre, randevu sayfası) listeler. | Okuma |
| List bookings | Randevuları durum (yaklaşan, geçmiş, iptal, onay bekleyen, tekrarlayan, hepsi), katılımcı e-postası ve başlangıç tarihine göre listeler; çıktı tetikleyiciyle aynı alanlara sahiptir. | Okuma |
Ön koşullar
- Bir cal.com (bulut) hesabı. Kendi sunucunuzda çalışan Cal.com kurulumları bu bağlantıda desteklenmez.
- Webhook ve API ücretsiz planda da kullanılabilir.
Adım adım kurulum
A) Cal.com'da API anahtarı
- Cal.com → Settings → Developer → API keys.
- New → ad:
OrqLabs, süre: Never expires (veya bir bitiş tarihi; süresi dolunca yenilemeniz gerekir). cal_live_…ile başlayan anahtarı kopyalayın.
B) OrqLabs'ta bağlama
- Entegrasyonlar → Cal.com → Bağla → Proje seçin.
- API key alanına anahtarı yapıştırın → Bağla.
OrqLabs profilinizi okur ve üç olay için tek bir webhook oluşturur. Cal.com'da Settings → Developer → Webhooks altında görünür. Her teslimat OrqLabs'ın ürettiği gizli anahtarla imzalanır (HMAC-SHA256); imzası tutmayan istekler reddedilir. Cal.com'daki Ping test düğmesi bağlantıyı dener ama iş akışı başlatmaz.
C) Tetikleyiciyi kurma
Entegrasyon olayı → Account: Cal.com bağlantınız → Event: istediğiniz olay. Tek bir etkinlik türü için Payload filter: {{ $json.eventType === "discovery-call" }}.
Örnek iş akışları
1) Yeni randevu → aday + hatırlatma hazırlığı
Entegrasyon olayı (CAL_COM · New booking) → Aday oluştur (e-posta {{ $json.email }}, ad {{ $json.name }}, telefon {{ $json.phone }}) → Metin üret ({{ $json.answers["Additional notes"] }} notuna göre görüşme gündemi) → Ekibe bildir.
2) İptal → yeniden randevu teklifi
Entegrasyon olayı (CAL_COM · Booking cancelled) → E-posta gönder (Uygun başka bir saat seçmek için: <randevu sayfanız>; neden: {{ $json.cancelReason }}).
3) Yarınki randevuların listesi
Zamanlama (her gün 17:00) → Cal.com → List bookings (Status Upcoming, Starting after {{ $date() }}, Limit 20) → Metin üret (özet) → Ekibe bildir.
Limitler
| Konu | Sınır |
|---|---|
| List bookings | İstek başına en fazla 100 randevu |
| Barındırma | Yalnızca cal.com bulut (api.cal.com) |
| Çok katılımcılı randevu | Üst düzey alanlar ilk katılımcıyı gösterir; tümü raw.payload.attendees içindedir |
| Takvim dosyası | Cal.com'un eklediği .ics içerikleri raw alanından çıkarılır |
Bağlantıyı test etme
Bağlantıyı test et adınızı, kullanıcı adınızı ve saat diliminizi gösterir.
Kimlik bilgilerini yenileme
Cal.com'da yeni anahtar üretin → OrqLabs'ta Kimlik bilgileri → Güncelle → Kaydet → eski anahtarı silin. Webhook anahtardan bağımsızdır. Bağlantıyı OrqLabs'ta silerseniz webhook da Cal.com'dan kaldırılır.
Sık karşılaşılan hatalar
| Hata | Olası neden | Çözüm |
|---|---|---|
AUTH – 401 "Invalid API Key" | Anahtar silindi, süresi doldu veya yanlış | Yeni anahtar girin |
FORBIDDEN – 403 | Anahtarın erişimi olmayan bir takım / organizasyon kaynağı | Kendi hesabınızın anahtarını kullanın |
| Olay gelmiyor | Webhook Cal.com'da silindi veya devre dışı | Ayrıntı panelinde Şimdi senkronize et |
| İmza hatası (401) | Webhook'un secret değeri Cal.com'da elle değiştirildi | Şimdi senkronize et ile yeniden kurun |
Sık sorulan sorular
Onay gerektiren etkinliklerde ne olur? Randevu talebi geldiğinde değil, siz onayladığınızda New booking gelir. Reddettiğiniz talepler tetiklemez.
Ekip etkinlikleri (round-robin) gelir mi? Webhook anahtarın sahibi olan kullanıcıya kurulur; bu kullanıcının ev sahibi olduğu randevular gelir.