Stripe ödeme hatası uyarıları: itirazlar, retler ve ölü webhook'lar

Bir itiraz açıldığında, bir abonelik tahsilatı başarısız olduğunda ya da bir ödeme transferi geri döndüğünde Stripe bunu zaten biliyor. Size e-postayla söylüyor. Daha gürültülü bir şey istiyorsanız, Stripe'ta bir Echobell kanal URL'sine işaret eden ikinci bir webhook uç noktası kaydedin, birkaç olay tipine abone olun ve bildirim tipini her olaya iliştirilmiş süreye göre seçin. İtirazların ve erken dolandırıcılık uyarılarının işleyen bir saati vardır; başarısız bir yenilemenin genellikle yoktur.

Bu rehber; hangi Stripe olaylarının sizi bölmeyi hak ettiğini, Stripe'ı yaklaşık beş dakikada Echobell'e nasıl bağlayacağınızı, her nesnede gerçekten var olan şablon alanlarını ve imza doğrulamasını atlarken kabul ettiğiniz ödünleşimi kapsıyor.

Gerçekten bölünmeyi hak eden olaylar

Ödeme uyarıları hep aynı şekilde bozulur: birisi hoşuna gittiği için payment_intent.succeeded'a abone olur, telefon günde kırk kez titrer ve altı hafta sonra bir itiraz bildirimi okunmadan akıp gider. Bunun yerine süreden başlayın. Olayı sekiz saat kaçırmanın hiçbir bedeli yoksa, size sekiz saniyede ulaşması gerekmiyordur.

Bu kademeler Echobell'in üç bildirim tipine karşılık gelir: Normal sıradan bir bildirimdir, Zaman duyarlı çoğu odak modunu deler, Çağrı ise gelen arama gibi görünür ve Rahatsız Etmeyin modunda bile çalar. Her abone kanal bazında kendi seviyesini seçer; yani kurucu ortağınız itirazları çağrı olarak alırken destek ekibinden bir arkadaşınız aynısını bildirim olarak alabilir.

Gerekenler

• Workbench'teki Webhooks sekmesine erişimi olan bir Stripe hesabı
• Kurulu Echobell (App Store / Google Play)
• Beş dakika. Sunucu yok, dağıtım yok, kod yok — imza doğrulaması istemiyorsanız; o da son bölümde.

Adım 1 — Olay tipi başına bir kanal

"Stripe" adında tek bir kanal yapıp her şeyi oraya göndermek cazip gelir. Yapmayın. Gövde şablonu ve panel bağlantısı itiraz, fatura ve ödeme transferi için farklıdır, çünkü her biri farklı bir nesne taşır — ve bu kurulumun bütün amacı, hiçbir şey açmadan bildirimin size ne olduğunu söylemesidir.

Olayın adını taşıyan bir kanal oluşturun: Stripe Disputes. Başlık ve gövde şablonlarını kilit ekranında tek bakışta okunacak şekilde yazın:

Title: 🔴 Dispute opened — {{data.object.reason}}
Body: Amount: {{data.object.amount}} {{data.object.currency}}
Charge: {{data.object.charge}}
Status: {{data.object.status}}

Bildirim kaydının doğru sayfayı açması için gelişmiş ayarlarda bağlantı şablonunu tanımlayın:

https://dashboard.stripe.com/disputes/{{data.object.id}}

Ardından kendinizi Çağrı tipiyle abone edin ve kanal detay ekranından webhook URL'sini kopyalayın. Şuna benzer: https://hook.echobell.one/t/<channel-token>.

Adım 2 — Stripe'ı kanala yönlendirin

Stripe panelinde Webhooks sekmesini açın ve bir olay hedefi oluşturun:

Oluşturduğunuz her kanal için tekrarlayın. Stripe hesap başına 16 webhook uç noktasına izin verir; uyarı kademesi başına bir tane için fazlasıyla yeter.

Adım 3 — Aslında ne geliyor

Stripe, Event nesnesini JSON olarak gönderir. Echobell gövdeyi olduğu gibi okur; dolayısıyla her alana şablonlarda ve koşullarda nokta gösterimiyle erişilebilir:

{
  "id": "evt_1P...",
  "type": "charge.dispute.created",
  "livemode": true,
  "created": 1757548800,
  "data": {
    "object": {
      "id": "dp_1P...",
      "amount": 4900,
      "currency": "usd",
      "reason": "fraudulent",
      "status": "needs_response",
      "charge": "ch_3P...",
      "evidence_details": { "due_by": 1759449600 }
    }
  }
}

Bu yükte insanları şaşırtan üç şey var:

Tutarlar en küçük para biriminde tam sayıdır. 4900 değerindeki bir amount 49,00 $ demektir. Echobell şablonları değerleri yerleştirir ve karşılaştırır ama aritmetik yapmaz; bu yüzden {{data.object.amount}} 4900 olarak görünür. Ya dürüstçe etiketleyin (Amount: 4900 (cents)) ya da son bölümdeki yönlendiriciyi kullanıp göndermeden önce 100'e bölün.

Zaman damgaları Unix saniyesidir. {{data.object.evidence_details.due_by}} bir tarih değil, 1759449600 olarak görünür. Kesin saatten çok bir sürenin varlığı önemliyse şablondan çıkarın — itiraz sayfası zaten gösteriyor — ve işi bağlantı şablonuna bırakın.

Alan adları nesneye göre değişir. Bir itirazda amount vardır; bir faturada amount_due, customer_email, attempt_count ve hosted_invoice_url; bir ödeme transferinde failure_message ve arrival_date; erken dolandırıcılık uyarısında fraud_type, actionable ve düz metin kimlik olarak charge bulunur. Olmayan bir değişken hata yerine boş dize olarak işlenir; dolayısıyla yanlış kanaldan kopyalanmış bir şablon sessizce başarısız olur. Olay tipi başına bir kanal önerisinin pratik sebebi budur.

Adım 4 — İrade gücüyle değil, koşullarla filtreleyin

Kanal koşulları, şablonlarla aynı ifade sözdizimini süslü parantezsiz kullanır ve herhangi bir teslimattan önce çalışır.

Her Stripe kanalına konması gereken:

livemode == true

Test modu trafiği — kendi stripe trigger denemeleriniz, bir arkadaşınızın sandbox'ta kurcalaması — artık telefonunuza ulaşmaz. Bunu bağlantının çalıştığını doğruladıktan sonra ekleyin, öncesinde değil.

Başarısız fatura kanalında bir eşik, küçük hesapları akşamınızın dışında tutar:

livemode == true && data.object.amount_due > 20000

Sent cinsinden "200 $ üzeri" diye okunur. Her ilk denemeyi değil de gerçekten tıkanmış tekrar denemeleri görmek isterseniz:

livemode == true && data.object.attempt_count > 1

Birden fazla olay tipini taşıyan tek bir uç noktayı tek kanala yönlendirdiyseniz, koşullar onları tekrar ayırır:

type == "charge.dispute.created" || type == "payout.failed"

Adım 5 — Uyarı yolunu bozulan şeyin dışında tutun

Burası şablonlardan daha değerli.

Üretimdeki webhook uç noktanız, teslimatın gerçekleştiği yerdir: erişim verir, veritabanına yazar, makbuzu gönderir. Dolayısıyla uygulamanız çöktüğünde birlikte çöken uç nokta da odur. Bu olduğunda Stripe üstel geri çekilmeyle üç güne kadar yeniden dener ve size bir e-posta yollar — teslim edilememiş webhook'lara dair bir e-posta ise diğer tüm Stripe e-postalarıyla birebir aynı görünür; bu yüzden pazartesi bulunur.

Webhook'un sessizce ölmesinin sebepleri sıkıcıdır. Stripe 3xx yönlendirmesini başarısızlık sayar; yani http'yi https'e yönlendirmeye ya da sona eğik çizgi eklemeye başlayan bir uç nokta olay almayı keser. TLS 1.2 veya üstünü gerektirir; süresi dolmuş ya da yanlış yapılandırılmış bir sertifika yeter. Geçen hafta birinin eklediği bir WAF kuralından dönen 403 de öyle.

Doğrudan Echobell'e bakan ikinci bir uç nokta bunların hiçbirini paylaşmaz. Başka bir sunucuda, başka bir sertifikayla, başka bir URL'dir ve uygulamanız yerdeyken çalmaya devam eder. Kural genelleşir: bir şeyin bozulduğunu söyleyen yol, bozulan şeyin içinden geçmemeli.

Yine de kendi uç noktanızın arızası görünür olsun istersiniz. Bir şey tuhaf geldiğinde Workbench'teki Event deliveries sekmesine bakın — olay başına Delivered, Pending ve Failed ile her denemenin HTTP durumunu gösterir. Stripe bir olayı panelden 15 güne kadar, CLI'da stripe events resend ile 30 güne kadar yeniden göndermenize izin verir; yani iki hafta içinde fark edilen bir boşluk telafi edilebilir.

İsteğe bağlı — Önce imzayı doğrulayın

Stripe'ın imzasının gerçekten kontrol edilmesini ve tutarların para gibi biçimlenmesini istiyorsanız, öne küçük bir yönlendirici koyun. Bu Cloudflare Worker olayı doğrular, Stripe'ın istediği gibi hemen 200 döner ve Echobell'e düz bir yük gönderir:

import Stripe from "stripe";

export default {
  async fetch(request, env, ctx) {
    const stripe = new Stripe(env.STRIPE_SECRET_KEY);
    const body = await request.text();

    let event;
    try {
      event = await stripe.webhooks.constructEventAsync(
        body,
        request.headers.get("stripe-signature"),
        env.STRIPE_WEBHOOK_SECRET,
      );
    } catch {
      return new Response("invalid signature", { status: 400 });
    }

    const invoice = event.data.object;
    ctx.waitUntil(
      fetch(env.ECHOBELL_HOOK_URL, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          customer: invoice.customer_email || invoice.customer,
          amount: (invoice.amount_due / 100).toFixed(2),
          currency: invoice.currency.toUpperCase(),
          attempt: invoice.attempt_count,
          externalLink: invoice.hosted_invoice_url,
        }),
      }),
    );

    return new Response("ok", { status: 200 });
  },
};

Biçimlendirme kodda yapıldığı için diğer taraftaki şablon çok daha temiz olur:

Title: 💳 Payment failed — {{currency}} {{amount}}
Body: Customer: {{customer}}
Attempt #{{attempt}}

externalLink özel bir değişkendir: bağlantı şablonu tanımlı değilse Echobell onu bildirim kaydının bağlantısı olarak kullanır; böylece barındırılan fatura sayfası tek dokunuş uzaklıkta olur.

Ödünleşimin şekline dikkat edin: artık kendisi de arızalanabilecek bir altyapı parçanız var — tam da Adım 5'in uyardığı şey. Makul bir orta yol: sahte uyarıların can sıkacağı yüksek hacimli kanalda imzaları doğrulamak, itiraz kanalını ise doğrudan bağlı bırakmak. Orada yersiz bir çalışın bedeli şaşkın bir bakış, kaçırılan bir çalışın bedeli ise itiraz edilen tutardır.

Bu kurulumun vermediği şeyler

• Nöbet rotasyonu ya da yükseltme yok. Çağrı kanalına abone olan herkes aynı anda çalar. Dört kişide özellik, kırk kişide sorundur; kırk kişide bir olay yönetimi platformu istersiniz.
• Yinelenenleri ayıklama yok. Stripe olay sırasını garanti etmez ve aynı olayı birden fazla kez iletebilir. Bir itiraz için iki çalış mümkündür.
• Onaylama yok. Bir insanın gördüğünü kaydeden bir şey yok; kimse yanıt vermezse ikinci kişiye yükselten de yok.
• "Ödemeler durdu" uyarısı yok. Stripe bir şeyler olduğunda olay yayınlar, durduğunda asla. Ödeme akışınız bozulursa hiçbir olay tetiklenmez. Bunun için sizin tarafınızda zamanlanmış bir işe ihtiyaç var: son bir saatteki tahsilat sayısı sıfırsa bir kanalı dürten bir iş — cron tabanlı bir ölü adam anahtarı.

Sorun giderme

Test olayı Stripe'ta 200 gösteriyor ama bildirim gelmedi. Echobell teslim etmediğinde bile JSON gövdesiyle 200 yanıtlar — Event deliveries sekmesinde yanıt gövdesine bakın. Geçerli uzunlukta bir token ile success: false, kanal token'ının yanlış olduğu anlamına gelir. success true ise muhtemel sebep bir koşuldur: livemode == true tasarımı gereği her test olayını engeller.

Stripe 405 Method Not Allowed bildiriyor. Kanalda POST Only açık ve bir şey GET göndermiş. Stripe her zaman POST yapar; yani bu bir bağlantı önizlemesi ya da tarayıcı sekmesidir, Stripe değil.

Bildirim boş alanlarla geliyor. Şablon yanlış nesneye bakıyor — fatura kanalında {{data.object.amount}} yazılmış ama oradaki alan amount_due. Gerçek bir olay gönderin, panelde açın ve JSON'u okuyun.

Haftalarca çalıştıktan sonra teslimatlar bozuluyor. Sertifikayı ve URL'nin önündeki her yönlendirmeyi kontrol edin. Doğrudan kullanılan bir kanal URL'sinde bu nadirdir; kendi dağıttığınız bir yönlendiricide her zamanki şüphelidir.

Sık sorulan sorular

Bir itiraz açıldığında Stripe beni arayabilir mi?

Kendi başına hayır. Stripe e-postayla, panelde, charge.dispute.created olayıyla ve Stripe Dashboard uygulamasını kullanıyorsanız bildirimle haber verir. Gerçek bir çalış için o olayı, abonelik tipi Çağrı olan bir kanala yönlendirin.

Stripe'ı Echobell'e bağlamak için kod yazmam gerekir mi?

Hayır. Stripe herkese açık herhangi bir HTTPS URL'sine JSON gönderir ve bir Echobell kanal URL'si tam olarak budur. Kod yalnızca Stripe-Signature başlığının doğrulanmasını ya da tutarların yeniden biçimlenmesini istiyorsanız gerekir.

Stripe'a üçüncü taraf bir webhook URL'si vermek güvenli mi?

Bilinçli bir ödünleşim. Stripe'ın gönderdiği yük müşteri ve ödeme meta verisi içerir ve Echobell ham webhook yüklerini kalıcı olarak saklamaz — işlenmiş bildirim cihazınızda durur. Vazgeçtiğiniz şey imza doğrulamasıdır: URL'yi öğrenen biri size çok inandırıcı bir sahte gönderebilir. Onu bir API anahtarı gibi görün ve doğrulanmasını istediğiniz her şey için yönlendirici desenini kullanın.

Uyarım neden 49,00 $ yerine 4900 gösteriyor?

Stripe tutarları en küçük para biriminde tam sayı olarak gönderir ve Echobell şablonları aritmetik yapmaz. Birimi şablonda belirtin ya da göndermeden önce bir yönlendiricide 100'e bölün.

Test modu olaylarının beni uyandırmasını nasıl engellerim?

Kanala livemode == true koşulunu ekleyin. Stripe her sandbox ve stripe trigger olayını livemode: false olarak işaretler.

Kurucu ortağım koltuk ücreti ödemeden aynı uyarıları alabilir mi?

Evet. Kanal bağlantısını paylaşın; her abone kendi bildirim tipini seçer. Biri itirazları çağrı olarak alırken bir diğeri normal bildirim olarak alabilir ve aboneler için koltuk başına ücret yoktur.

Başarılı ödemeler için uyarı kurmalı mıyım?

Yalnızca kısa bir süre ve yalnızca işletme her ödemenin hâlâ bir olay sayıldığı kadar küçükken. Başarılı ödeme bildirimi rutine dönüştüğü anda, önemli olanlara verdiğiniz tepkiyi aşındırmaya başlar — uyarı yorgunluğunun ardındaki temel mekanizma budur.

Toparlarsak

Kurulumun tamamı şudur: Echobell kanalı başına bir Stripe olay hedefi, bir livemode == true koşulu ve çağrı kademesini saati işleyen olaylara saklama disiplini. İtirazların ve erken dolandırıcılık uyarılarının saati vardır. 9 $'lık bir plandaki başarısız yenilemenin yoktur; varmış gibi davranmak ise saati gerçekten işleyen olayı uykuda geçirmenin tam yoludur.

Echobell'i iPhone için indirin ya da Google Play'den edinin, önce itiraz kanalını oluşturun ve bu yola gerçek bir şey emanet etmeden önce bir kez stripe trigger charge.dispute.created çalıştırın.

İlgili

• Webhook entegrasyon belgeleri
• Kanal koşulları referansı
• Geliştiriciler için uyarı yorgunluğu rehberi
• Cron işi hatası uyarıları
• Zapier webhook bildirimlerini telefona göndermek