Skip to main content
Webhook, bir olay gerçekleştiğinde Whop’un sunucunuza gönderdiği bir POST isteğidir. Olay örnekleri: bir ödeme başarılı olur, bir üyelik etkinleşir, bir itiraz açılır. Herkese açık bir URL kaydedersiniz. Abone olduğunuz olaylardan biri her gerçekleştiğinde Whop bu URL’ye imzalı bir JSON olayı gönderir.
Whop webhook’ları Standard Webhooks spesifikasyonunu kullanır. Whop SDK’ları imzayı doğrular ve olayı tek bir çağrıda ayrıştırır. Go için bu sayfanın altındaki SDK olmadan doğrulayın bölümünü kullanın.

Bir webhook nasıl görünür

Her olay tek bir POST isteğidir:
Zarf, tıpkı data gibi webhook’unuzun api_version_date sabitlemesini izler. 2026-08-14 öncesine sabitlenmiş webhook’lar ve sabitlemesi olmayan webhook’lar, hesap alanını account_id yerine company_id olarak alır. HTTP istek başlıkları da aynı şekilde sürümlenir: gelecekteki herhangi bir başlık değişikliği tarihli bir API sürümü olarak yayınlanır ve sabitlemeniz entegre ettiğiniz başlıkları korur. Dört başlık sözleşme gereği dondurulmuştur ve hiçbir sürümde değişmez: webhook-id, webhook-signature, webhook-timestamp ve content-type; imza doğrulaması her sabitlemede aynı şekilde çalışır. İsteğe bağlı bir zarf alanı neyin değiştiğini açıklar:
  • previous_attributes: değişiklikleri yakalayan .updated olaylarında (account.updated, product.updated, plan.updated ve shipment.updated) bulunur; değişen data alanlarının eski değerlerini alan adına göre anahtarlanmış şekilde içeren bir nesnedir. Hesabı “Shine Time Auto Detailing” olarak yeniden adlandırmak {"title": "Webb's Mobile Detailing"} değerini iletir; bu, değişen her alanın yazma işleminden önceki değeridir. Alan yoksa, olay için değişiklik yakalama mevcut değildi. Değerler, tıpkı data gibi webhook’unuzun api_version_date sabitlemesini izler.

Bir abonelik ödemesini kurtarın

Banka alıcıdan oturum dışı bir ücretlendirmeyi doğrulamasını istediğinde Whop payment.requires_action olayını yayar. Alıcının Whop’a giriş yapıp o ödeme için 3D Secure’u tamamlayabilmesi için olayın data.recovery_url değerini alıcıya gönderin. Oturum içi ödemeler bunu hiçbir zaman yaymaz, çünkü alıcı doğrulamayı zaten tamamlamaktadır. Başarısız bir abonelik yenilemesi ayrıca payment.failed olayını da yayar. Mevcut olduğunda nedeni öğrenmek için data.decline_code ve data.failure_message değerlerini inceleyin; data.recovery_url mevcutsa onu da orada kullanın. Aynı recovery_url alanı, Payment kaynağını aldığınızda da kullanılabilir. Ödeme listeleri kurtarma bağlantılarını içermez. Kimlik doğrulama kurtarması kullanılamadığında veya member:basic:read izniniz olmadığında değer null olur. Bağlantıyı açmak bir ücretlendirme başlatmaz: alıcının onaylaması gerekir ve Whop ödemenin hâlâ kurtarılabilir olup olmadığını kontrol eder. Kurtarmadan sonra sonuç için payment.succeeded veya payment.failed olaylarını ele almaya devam edin.

Bir webhook oluşturun

Yanıt webhook_secret değerini içerir. API bu değeri yalnızca bir kez gösterir. Hemen saklayın. resource_id (webhook’un sahibi olan hesap veya uygulama) ve child_resource_events dahil tüm alanlar için Webhooks API referansına bakın. Bir uygulamaya ait olan webhook, o uygulamanın yükleme ve kaldırma olaylarını da alır. Bkz. Uygulama Kurulumları.

Olayları doğrulayın ve ele alın

Bir yükü kullanmadan önce her zaman imzayı doğrulayın.
1

İmzalama anahtarınızı saklayın

Doğrulama bir SDK istemcisine değil, gizli anahtara ihtiyaç duyar. API’nin döndürdüğü değeri WHOP_WEBHOOK_SECRET olarak saklayın ve yardımcıya tam olarak Whop’un size verdiği şekilde, yani bir ws_ dizesi olarak iletin. Öneki kaldırmayın ve base64 ile kodlamayın. Anahtarı yardımcı türetir.
2

Olayları sunucunuzda ele alın

Tek bir çağrı imzayı doğrular ve ayrıştırılmış olayı döndürür. İmza yanlışsa çağrı hata fırlatır ve işleyiciniz yükü hiçbir zaman görmez.
Yardımcı, tipli bir olay nesnesi değil, ayrıştırılmış gövdeyi döndürür: TypeScript’te düz bir nesne, Python’da bir dict ve Ruby’de sembol anahtarlı bir Hash. Gösterildiği gibi type değerine göre dallanın ve data değerini okuyun.
Yanıt vermeden önce yalnızca gerekli işi yapın: olayı doğrulayın, işi bir kuyruğa koyun ve 200 döndürün. TypeScript örneği @vercel/functions paketindeki waitUntil fonksiyonunu kullanır. Diğer çalışma ortamlarında framework’ünüzün arka plan görevi fonksiyonunu veya bir iş kuyruğunu kullanın.
Whop, {webhook-id}.{webhook-timestamp}.{raw body} dizesini HMAC-SHA256 ile imzalar. Anahtar, ws_... gizli anahtarınızdır. webhook-signature başlığı sonucu base64 olarak içerir: v1,<signature>.Bir isteği doğrulamak için: HMAC’i ham istek gövdesi üzerinden hesaplayın, sonucu base64 ile kodlayın ve sabit zamanlı bir karşılaştırmayla başlık değeriyle karşılaştırın. webhook-timestamp değeri geçerli zamandan 5 dakikadan fazla uzaksa isteği reddedin. Bu, yeniden oynatma saldırılarını önler. SDK doğrulayıcıları bu sınırı otomatik olarak uygular.

Uç noktanızı test edin

  • Bir test olayı gönderin. Kontrol panelinde webhook’un menüsünü açın ve bir test olayı seçin. Ya da POST /api/v1/webhooks/{id}/test çağırın. Whop URL’nize örnek bir yük gönderir ve sunucunuzdan gelen yanıt durumunu ve gövdesini döndürür.
  • Teslimatları inceleyin. Whop her teslimatı 30 gün boyunca saklar: istek, yanıt kodu, yanıt gövdesi ve zamanlama. Teslimatları kontrol panelinde veya GET /api/v1/webhooks/{id}/deliveries ile görün.
Bir webhook URL’sine herkese açık internetten erişilebilmelidir. Whop localhost ve özel ağ adreslerini reddeder. Yerel geliştirme için herkese açık bir URL’yi makinenize yönlendirmek üzere ngrok veya Cloudflare Tunnel kullanın. Tünel URL’sini kaydedin.

Teslimat

5 saniyeden kısa sürede 2xx durumuyla yanıt verin. Diğer tüm sonuçlar başarısız denemelerdir: zaman aşımı, hata durumu veya yönlendirme. Whop yönlendirmeleri izlemez. Whop her olayı en az bir kez teslim eder. Aynı olay birden fazla kez gelebilir. İşleyicinizi idempotent yapın. Bir teslimatın her yeniden denemesi aynı webhook-id değerine sahiptir. webhook-id değerini saklayın ve yinelenenleri yok sayın. Whop başarısız teslimatları yaklaşık 3 gün boyunca yeniden dener. İlk denemeden sonra Whop artan gecikmelerle 12 kez yeniden dener: 30 saniye, 2 dakika, 8 dakika, 30 dakika, 1 saat, 3 saat, 6 saat ve ardından her 12 saatte bir. Tüm zamanlama yaklaşık 71 saattir. Teslimatların sırası garanti edilmez. Daha yeni bir olay, daha eski bir olaydan önce gelebilir. Her olayı bağımsız olarak işleyin. Sıra önemliyse güncel durumu API’den okuyun. Whop başarısız olmaya devam eden uç noktaları devre dışı bırakır. Uç noktanıza yapılan tüm teslimatlar 24 saat boyunca başarısız olursa Whop hesabınıza bir uyarı e-postası gönderir. Başarısızlıklar 72 saat boyunca devam ederse ve 10 veya daha fazla teslimat başarısız olduysa Whop webhook’u devre dışı bırakır ve ikinci bir e-posta gönderir. Webhook’u yeniden etkinleştirmek için kontrol panelini kullanın veya "enabled": true ile PATCH /api/v1/webhooks/{id} gönderin. Bu, başarısızlık geçmişini sıfırlar. Whop, webhook kapalıyken gerçekleşen olayları göndermez. Kaçırdığınız verileri bulmak için API’yi okuyun.

Webhook teslimatı sorunlarını giderin

İmza hatalarını, yeniden denemeleri, yinelenen olayları ve yerel tünel sorunlarını giderin.

Olaylar ve sürümler

İki sürüm alanı, uç noktanızın aldığı verileri kontrol eder:
  • api_version: zarf biçimi. v1 kullanın. Bu sayfa yalnızca v1 sürümünü açıklar. Eski v2 ve v5 biçimleri eski entegrasyonlar için mevcuttur ve Standard Webhooks imzalarını kullanmaz. Yeni entegrasyonlar için bunları kullanmayın.
  • api_version_date: data alanının ve zarfın kendisinin yapısını belirleyen tarihli API sürümü (örneğin 2026-08-14 tarihinden itibaren olan sabitlemeler, eski sabitlemelerin company_id taşıdığı yerde account_id taşır). REST okumalarındaki Api-Version-Date başlığıyla aynı şekilde çalışır. API ile bir webhook oluştururken bunu ayarlayın. Böylece API değiştiğinde yük yapısı sabit kalır. Sabitlemesi olmayan webhook’lar ilk yük ve zarf yapılarını korur. İstisna: yalnızca güncel API’de bulunan kaynaklar (kartlar, varyantlar, transferler, takaslar, yatırmalar, dışa aktarmalar) her zaman en son data yapısını alır; zarf yine de sabitlemeyi izler.
Olay adları resource.action biçimindedir. Tablodaki her olay, yük şemasını içeren bir referans sayfasına bağlanır:

Sonraki adımlar

Ödeme kabul edin

Siparişleri yerine getirmek için ödeme sayfasıyla birlikte payment.succeeded webhook’larını kullanın.

Ödeme yöntemlerini kaydedin

Müşterilerden daha sonra ücret almak için kurulum niyetlerini ve webhook’ları kullanın.

Hızlı başlangıç

Webhook’ların ödeme sayfası, transferler ve KYC ile nasıl çalıştığını görün.

Webhooks API referansı

Tüm uç noktalar ve alanlar: oluşturma, güncelleme, test, teslimatlar.