Seorang pelanggan membayar, Stripe mengirimkan peristiwa payment_intent.succeeded ke backend Anda, dan endpoint Anda seharusnya menandai pesanan sebagai lunas. Langkah terakhir inilah yang seringkali rusak tanpa disadari. Webhook mendarat, penangan Anda mengalami kesalahan, dan tidak ada yang menyadarinya sampai ada tiket dukungan yang menyatakan "Saya sudah membayar, tetapi akun saya masih menunjukkan belum lunas." Anda menginginkan pengujian di CI yang membuktikan peristiwa tersebut tiba dan ditangani dengan benar, setiap kali Anda melakukan pengiriman.
Bagian yang rumit adalah bahwa webhook adalah panggilan HTTP masuk dari Stripe ke Anda, bukan permintaan yang Anda buat. Sebagian besar alat pengujian API dibuat untuk mengirim permintaan dan memeriksa responsnya, yang merupakan bentuk yang berlawanan. Jadi pertanyaannya menjadi: bagaimana Anda menguji sesuatu yang tiba sesuai jadwalnya sendiri, di dalam eksekusi CI, tanpa pengawasan manusia? Panduan ini menunjukkan cara yang jujur dan didukung untuk melakukannya dengan Apidog, dan ini dimulai dengan batasan yang perlu Anda ketahui di awal. Jika Anda ingin gambaran yang lebih luas tentang pengujian endpoint berbasis peristiwa terlebih dahulu, panduan kami tentang cara menguji webhook menyiapkan panggung, dan dokumentasi webhook Stripe sendiri membahas model pengiriman peristiwa.
Batasan yang harus Anda rancang
Inilah fakta penting, yang dinyatakan dengan jelas dalam dokumen Apidog sendiri: "Apidog tidak secara bawaan mendukung mendengarkan webhook." Apidog tidak berada di URL publik dan menangkap panggilan masuk Stripe secara real-time. Jika Anda berharap untuk mengarahkan Stripe ke pendengar Apidog dan melihat peristiwa masuk, jalur itu tidak ada.
Kedengarannya seperti jalan buntu. Tapi tidak. Ini hanya mengubah bentuk pengujian. Alih-alih mencegat webhook saat tiba, Anda menangkapnya di backend Anda sendiri, menyimpannya, lalu meminta Apidog menanyakan catatan yang tersimpan itu dan memverifikasinya. Tangkap dulu, validasi kedua. Setelah Anda menerima pembagian itu, seluruh alur kerja menjadi lugas dan, yang penting, sangat cocok dengan CI karena kueri database bersifat deterministik dan dapat diulang.
Seperti apa pola tangkap-lalu-kueri itu
Pola yang direkomendasikan oleh dokumen Apidog memiliki empat bagian yang bergerak:
- Buat endpoint di layanan backend Anda untuk menangkap webhook Stripe yang masuk.
- Simpan data peristiwa webhook di tabel
Stripe event logsdi database Anda. - Gunakan Post-Request Processor Apidog untuk mengkueri database Anda.
- Ambil peristiwa webhook yang tersimpan dan validasi terhadap hasil yang diharapkan.
Dua dari langkah-langkah itu ada di kode Anda, dan dua ada di Apidog. Endpoint penangkapan dan tabel logging adalah tanggung jawab Anda untuk dibuat, karena berjalan di dalam aplikasi Anda sendiri. Tugas Apidog dimulai setelah peristiwa ada di database Anda: ia terhubung ke database itu dan membaca baris kembali untuk mengonfirmasi peristiwa ditangani sesuai harapan Anda. Pertahankan pembagian itu dengan jelas dan sisanya akan berjalan dengan sendirinya.
Langkah 1: buat endpoint penangkapan
Backend Anda membutuhkan rute yang dapat di-POST oleh Stripe. Ini adalah kode aplikasi biasa, bukan fitur Apidog. Penangan Express minimal yang memverifikasi tanda tangan dan mencatat peristiwa terlihat seperti ini:
import express from "express";
import Stripe from "stripe";
const app = express();
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET;
app.post(
"/webhooks/stripe",
express.raw({ type: "application/json" }),
async (req, res) => {
let event;
try {
event = stripe.webhooks.constructEvent(
req.body,
req.headers["stripe-signature"],
endpointSecret
);
} catch (err) {
return res.status(400).send(`Signature check failed: ${err.message}`);
}
// Persist the event so a test can read it back later.
await db.query(
`INSERT INTO stripe_event_logs (event_id, type, payload, handled_at)
VALUES ($1, $2, $3, now())
ON CONFLICT (event_id) DO NOTHING`,
[event.id, event.type, JSON.stringify(event.data.object)]
);
if (event.type === "payment_intent.succeeded") {
const intent = event.data.object;
await markOrderPaid(intent.metadata.order_id);
}
res.json({ received: true });
}
);
Dua hal penting di sini. Pertama, Anda memverifikasi tanda tangan Stripe dengan constructEvent sebelum mempercayai apa pun, yang merupakan langkah keamanan yang tidak dapat dinegosiasikan untuk setiap penerima webhook. Jika Anda ingin alasan lengkap di balik pemeriksaan itu, panduan kami tentang verifikasi tanda tangan webhook membahas mengapa perbandingan badan mentah adalah satu-satunya cara aman untuk melakukannya. Kedua, Anda menulis peristiwa ke tabel Stripe event logs. Baris itulah yang akan dibaca Apidog. Klausul ON CONFLICT DO NOTHING menjaga log tetap idempoten, karena Stripe dapat mengirimkan peristiwa yang sama lebih dari sekali.
Langkah 2: hubungkan database Anda di lingkungan Apidog
Apidog mendukung koneksi ke database di lingkungan yang sesuai, dan koneksi itulah yang membuat seluruh pola ini berfungsi. Siapkan koneksi database untuk lingkungan yang ditargetkan oleh eksekusi CI Anda, apakah itu Postgres staging atau database pengujian khusus. Setelah koneksi terpasang, langkah pengujian dapat menjalankan SQL terhadapnya dan menarik kembali baris-baris nyata.
Sesuaikan koneksi dengan lingkungan yang Anda uji. Pengujian yang berjalan terhadap staging harus mengkueri database staging, sehingga peristiwa yang dipicu oleh pengujian Anda adalah peristiwa yang dibaca oleh pengujian Anda. Lingkungan yang tidak cocok adalah alasan paling umum mengapa endpoint penangkapan yang berhasil masih gagal dalam verifikasi.
Langkah 3: tambahkan Post-Request Processor untuk mengkueri log
Inilah intinya. Post-Request Processor adalah fitur Apidog yang mengkueri database Anda dan memvalidasi peristiwa webhook yang dicatat di dalam pengujian. Anda melampirkannya ke permintaan dalam skenario pengujian Anda. Setelah permintaan berjalan, prosesor mengeksekusi SQL Anda, membaca peristiwa yang tersimpan, dan memungkinkan Anda memverifikasi hasilnya.
Alur realistis untuk kasus payment_intent.succeeded:
- Skenario pengujian Anda memicu pembayaran. Ini mungkin permintaan yang membuat `payment intent` dan mengonfirmasinya dalam mode uji Stripe, atau _fixture_ yang memicu peristiwa uji yang diketahui di endpoint penangkapan Anda.
- Stripe mengirimkan webhook ke rute
/webhooks/stripeAnda, yang memverifikasi tanda tangan dan menulis baris kestripe_event_logs. Post-Request Processorpada langkah berikutnya mengkueri tabel tersebut untuk peristiwa tersebut.
Kueri yang dijalankan prosesor adalah SQL biasa:
SELECT event_id, type, payload, handled_at
FROM stripe_event_logs
WHERE type = 'payment_intent.succeeded'
ORDER BY handled_at DESC
LIMIT 1;
Anda kemudian memverifikasi terhadap baris yang dikembalikan. Pengujian lulus ketika data yang dicatat sesuai dengan harapan Anda: type adalah payment_intent.succeeded, event_id cocok dengan yang Anda picu, payload jumlahnya sama dengan yang Anda kenakan, dan handled_at terisi, yang membuktikan penangan Anda benar-benar berjalan daripada baris menjadi _placeholder_. Ambil peristiwa webhook yang tersimpan, bandingkan dengan hasil yang diharapkan, dan biarkan verifikasi memutuskan lulus atau gagal.
Karena waktu pengiriman webhook tidak instan, berikan waktu sebentar agar peristiwa tiba sebelum Anda mengkueri. Langkah penundaan singkat, atau _polling loop_ yang mencoba kembali kueri beberapa kali sebelum gagal, mencegah pengujian berlomba dengan pengiriman Stripe. Ini adalah satu-satunya tempat di mana sifat asinkron webhook bocor ke desain pengujian Anda, dan jendela percobaan ulang yang kecil menanganinya dengan bersih.
Catatan tentang penerusan real-time selama pengembangan lokal
Pola tangkap-lalu-kueri dibangun untuk CI, di mana database dan catatan yang tersimpan adalah persis yang Anda inginkan. Pengembangan lokal adalah situasi yang berbeda. Saat Anda menulis penangan di laptop Anda, Stripe tidak dapat menjangkau localhost secara langsung, jadi Anda memerlukan sesuatu untuk meneruskan peristiwa ke mesin Anda secara real-time.
Untuk itu, dokumen Apidog menunjuk ke layanan relai webhook, menyebut Stripe CLI dan Ngrok sebagai contoh. Stripe CLI dapat mendengarkan dan meneruskan peristiwa langsung ke port lokal Anda:
stripe listen --forward-to localhost:3000/webhooks/stripe
Itu memberi Anda peristiwa langsung saat Anda membangun penangan. Ngrok melakukan pekerjaan yang sama dengan mengekspos port lokal Anda pada URL publik yang Anda daftarkan sebagai endpoint Stripe. Gunakan ini untuk lingkaran pengembangan internal, lalu andalkan database plus alur Post-Request Processor untuk verifikasi yang berjalan di _pipeline_ Anda. Keduanya saling melengkapi: relai untuk membangun, tangkap-lalu-kueri untuk membuktikan.
Jangan salah mengira ini dengan fitur Webhook bawaan Apidog
Apidog memang memiliki fitur yang secara harfiah disebut Webhook, dan mudah untuk berasumsi bahwa begitulah cara Anda menangkap peristiwa Stripe. Bukan begitu, dan mencampurkannya akan menghabiskan waktu Anda. Fitur Webhook bawaan adalah untuk mendefinisikan dan mendokumentasikan _outbound webhook_, yang berarti endpoint HTTP yang dipanggil oleh sistem Anda sendiri ketika suatu peristiwa terjadi. Sistem memulai panggilan ke URL eksternal, yang merupakan kebalikan dari endpoint biasa di mana klien memanggil Anda. Ini digunakan untuk mendeskripsikan notifikasi perubahan status dan hasil tugas asinkron dalam dokumen API Anda, bukan untuk menerima panggilan masuk Stripe.
Jika Anda ingin mendokumentasikan salah satu _outbound webhook_ Anda sendiri, alurnya singkat:
- Klik ikon
+di sidebar kiri. - Pilih
New Other Protocol APIs, laluWebhook. - Isi kolom yang diperlukan:
Request Method(biasanya POST),Webhook Name,Debug URLopsional untuk pengujian saja, danOther Infountuk _body_ permintaan, _headers_, dan konfigurasi. - Klik
Save.
Untuk mencobanya, masukkan URL di kolom Debug URL dan klik Send untuk mensimulasikan panggilan webhook. Satu peringatan yang perlu diingat: Debug URL hanya untuk pengujian dan tidak akan muncul di dokumentasi yang diterbitkan atau ekspor OpenAPI Anda. Untuk pembahasan lebih lengkap tentang merancang dan mendokumentasikan _callback_ peristiwa, artikel kami tentang webhook dalam desain API membahas di mana mereka cocok. Versi singkat untuk artikel ini: fitur Webhook bawaan mendefinisikan peristiwa _outbound_ Anda, dan pola tangkap-lalu-kueri memvalidasi peristiwa _inbound_ Stripe. Simpan keduanya dalam kotak mental yang terpisah.
Variasi dan penguatan
Setelah verifikasi dasar berfungsi, beberapa penyempurnaan membuatnya layak produksi. Pertama, verifikasi lebih dari sekadar jenis peristiwa. Periksa event_id secara _end-to-end_ sehingga Anda tahu peristiwa persis yang Anda picu adalah yang Anda validasi, bukan sisa dari eksekusi sebelumnya. Pangkas atau cakup tabel stripe_event_logs per eksekusi pengujian jika peristiwa menumpuk.
Kedua, uji jalur kegagalan. Picu peristiwa yang seharusnya ditolak oleh penangan Anda, tanda tangan yang buruk atau jenis yang tidak terduga, dan pastikan tidak ada _timestamp_ handled_at yang ditulis. _Test suite_ webhook yang hanya memeriksa jalur positif akan melewatkan kasus yang sebenarnya membuat Anda terbangun pukul 2 pagi. Catatan kami tentang praktik terbaik webhook pembayaran membahas idempotensi dan perilaku percobaan ulang yang patut dikodekan dalam pengujian ini.
Ketiga, pertahankan verifikasi yang ketat terhadap makna bisnis, bukan hanya pengiriman. "Peristiwa tiba" lebih lemah daripada "pesanan berpindah ke lunas." Jika penangan Anda memperbarui tabel orders, tambahkan kueri kedua yang mengonfirmasi perubahan status hilir, sehingga pengujian membuktikan seluruh rantai dan bukan hanya penulisan log.
Anda juga bisa membawa ini melampaui gerbang penggabungan (_merge gate_). Setelah skenario disimpan di Apidog, jadwalkan untuk berjalan secara berkala sehingga penangan webhook yang rusak muncul bahkan di antara _deploy_. Panduan kami tentang cara menjadwalkan pengujian API di Apidog menunjukkan cara menempatkan validasi yang sama ini pada _timer_.
Otomatiskan alur kerja dengan Apidog CLI
Semua hal di atas akan terbayar jika berjalan tanpa pengawasan, dan di sinilah Apidog CLI berperan. Ini pada dasarnya adalah cerita CI, jadi menyambungkan skenario yang tersimpan ke _pipeline_ Anda adalah penyelesaian alami. Instal CLI dan otentikasi dengan token Anda:
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Kemudian jalankan skenario validasi webhook Anda yang tersimpan secara _headless_ terhadap lingkungan yang database-nya menyimpan log peristiwa:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <SCENARIO_ID> -e <ENV_ID> -r cli
Di sini -t adalah id skenario pengujian, -e adalah id lingkungan, dan -r memilih _reporter_. Gunakan -r html,cli jika Anda ingin laporan yang dapat dijelajahi di samping _output_ konsol untuk _artifact_ CI Anda. Skenario membawa Post-Request Processor dan kueri database-nya, jadi satu perintah memicu alur, membaca baris stripe_event_logs, dan mengembalikan kode keluar non-nol jika verifikasi gagal, yang persis seperti yang dibutuhkan _pipeline_ untuk mengatur persetujuan penggabungan. Panduan instalasi Apidog CLI mencakup pengaturan token, dan panduan alur kerja CI/CD pipeline kami menunjukkan seluruh pengaturan GitHub Actions di sekitar perintah ini.
Pertanyaan yang Sering Diajukan
Bisakah Apidog menerima webhook Stripe secara langsung? Tidak. Dokumen Apidog dengan jelas menyatakan bahwa ia "tidak secara bawaan mendukung mendengarkan webhook." Anda menangkap peristiwa di endpoint backend Anda sendiri, menyimpannya dalam database, dan Apidog membacanya kembali dengan Post-Request Processor. Untuk penerusan _real-time_ selama pengembangan lokal, gunakan relai seperti Stripe CLI atau Ngrok sebagai gantinya.
Di mana sebenarnya verifikasi terjadi? Di dalam langkah Post-Request Processor pada permintaan dalam skenario pengujian Anda. Ia mengkueri tabel Stripe event logs Anda melalui koneksi database yang Anda konfigurasikan di lingkungan, mengambil peristiwa yang tersimpan, dan membandingkannya dengan nilai yang Anda harapkan. Pengujian lulus ketika data yang dicatat cocok.
Apakah saya perlu paket berbayar untuk alur validasi database? Dokumen Apidog untuk alur kerja ini tidak menyatakan pembatasan paket apa pun, jadi panduan ini tidak akan mengada-ada. Jawaban jujurnya adalah memeriksa detail paket saat ini di halaman harga. Anda dapat Mengunduh Apidog dan menyiapkan proyek pengujian untuk melihat Post-Request Processor dan koneksi database lingkungan sendiri.
Bagaimana saya menangani penundaan antara pemicuan dan pengiriman? Pengiriman webhook tidak instan, jadi tambahkan penundaan singkat atau percobaan ulang _polling_ sebelum kueri agar pengujian Anda tidak berlomba dengan Stripe. Beberapa percobaan ulang selama beberapa detik biasanya sudah cukup. Jika Anda baru dalam memverifikasi endpoint asinkron, mulailah dengan panduan umum cara menguji webhook sebelum melapisi spesifik Stripe.
Apakah fitur Webhook bawaan berguna di sini sama sekali? Tidak untuk menangkap peristiwa Stripe. Fitur itu mendefinisikan dan mendokumentasikan _outbound webhook_ Anda sendiri, di mana sistem Anda memanggil URL eksternal. Ini adalah alat dokumentasi dan desain, terpisah dari pola tangkap-lalu-kueri _inbound_ yang digunakan artikel ini. Pisahkan keduanya dengan jelas.
Kesimpulan
Anda tidak bisa mengarahkan Stripe ke Apidog dan menangkap peristiwa secara langsung, dan berpura-pura sebaliknya akan mengakibatkan sore yang membuat frustrasi. Jalur yang didukung lebih bersih dari yang terlihat pada awalnya: tangkap webhook di endpoint Anda sendiri, catat ke tabel Stripe event logs, lalu biarkan Post-Request Processor Apidog mengkueri catatan itu dan memverifikasi peristiwa telah ditangani. Bungkus skenario yang tersimpan dalam apidog run dan _pipeline_ Anda membuktikan, pada setiap penggabungan, bahwa peristiwa pembayaran nyata memindahkan pesanan Anda ke status lunas. Coba gratis, tidak perlu kartu kredit, dan lakukan verifikasi nyata di balik webhook yang paling penting.