Untuk menguji sebuah webhook, Anda memberikan URL yang dapat dijangkau kepada penyedia, memicu peristiwa nyata, dan kemudian mengonfirmasi bahwa penangan Anda menerima payload dan bereaksi dengan benar. Bagian yang sulit adalah bahwa aplikasi Anda adalah penerima, bukan pemanggil, jadi Anda tidak bisa begitu saja menekan "Kirim" dan membaca responsnya. Panduan ini menjelaskan alat yang Anda butuhkan (layanan inspeksi, terowongan lokal, pemicu penyedia) dan proses berulang untuk memastikan penangan Anda bekerja secara menyeluruh.
Mengapa webhook lebih sulit diuji dibandingkan API normal
Dengan panggilan API normal, Anda mengontrol permintaannya. Anda memilih metode, mengatur body, menjalankannya, dan membaca responsnya. Webhook membalikkan hal itu. Penyedia mengirimkan permintaan kepada Anda, sesuai jadwalnya sendiri, dengan payload yang ditentukannya. Pembalikan peran ini menciptakan empat masalah pengujian.
Pertama, Anda tidak dapat memicu peristiwa itu sendiri secara default. Peristiwa payment_intent.succeeded hanya dipicu ketika Stripe memutuskan demikian, jadi Anda memerlukan alat penyedia untuk memaksakannya.
Kedua, pengiriman bersifat asinkron. Peristiwa tiba kapan pun tindakan hulu selesai, sehingga pengujian Anda harus menangkap permintaan masuk daripada memblokir nilai yang dikembalikan.
Ketiga, bentuk payload ditentukan oleh penyedia. Penangan Anda harus mengurai dengan tepat apa yang dikirim oleh GitHub, Stripe, atau Slack.
Keempat, sebagian besar penyedia menandatangani permintaan mereka. Titik akhir Anda harus memverifikasi header tanda tangan sebelum mempercayai body, dan pengujian yang melewatkan ini menyembunyikan bug nyata. Untuk tinjauan lebih mendalam, lihat panduan kami tentang verifikasi tanda tangan webhook.
Jika Anda masih memutuskan apakah webhook adalah pola yang tepat untuk integrasi Anda, webhook vs polling dan webhook vs WebSocket membandingkan trade-off.
Toolkit pengujian webhook
Anda akan menggunakan empat jenis alat, seringkali dalam sesi yang sama: layanan penangkap untuk melihat payload mentah, terowongan untuk mencapai laptop Anda, pemicu penyedia untuk memicu peristiwa nyata, dan alat penegasan untuk memverifikasi penangan Anda.
1. Layanan inspeksi dan penangkap
Sebelum Anda menulis satu baris kode penangan pun, arahkan penyedia ke URL sementara dan lihat apa yang sebenarnya dikirimkannya. Layanan ini memberi Anda titik akhir publik dan menampilkan setiap permintaan secara real time.
webhook.site memberi Anda URL dan alamat email acak unik saat halaman dimuat. Segala sesuatu yang dikirimkan ke sana akan langsung muncul: body lengkap, header, dan metode. URL gratis kedaluwarsa setelah 7 hari dan dibatasi 100 permintaan, dengan ukuran permintaan maksimum 10 MB. Paket berbayar menambahkan URL permanen, permintaan tak terbatas, dan riwayat 10.000 permintaan terbaru yang disimpan.
Beeceptor menawarkan titik akhir HTTPS gratis yang dapat Anda gunakan sebagai penerima webhook dan memeriksa payload masuk secara real time. Ia juga menyediakan titik akhir server tiruan, sehingga Anda dapat menangkap dan mensimulasikan dari alat yang sama.
Pipedream RequestBin adalah alat penangkap permintaan lain yang banyak digunakan. Periksa dokumennya saat ini untuk spesifikasi tingkatan, karena layanan penangkap sering mengubah batas gratisnya.
Gunakan ini untuk menjawab satu pertanyaan: seperti apa bentuk payload sebenarnya? Salin sampel untuk nanti, saat Anda membuat pengujian berulang.
2. Pengembangan lokal: mengekspos localhost dengan terowongan
Penyedia tidak dapat menjangkau localhost:3000 di mesin Anda. Terowongan membuat URL HTTPS publik yang meneruskan lalu lintas ke port lokal Anda, sehingga Anda dapat menjalankan penangan Anda di editor dan mendebugnya secara langsung.
ngrok adalah pilihan umum. Pasang, otentikasi sekali, lalu teruskan port.
brew install ngrok # macOS
ngrok config add-authtoken $YOUR_TOKEN
ngrok http 3000 # meneruskan URL HTTPS publik ke localhost:3000
Akun ngrok gratis mendapatkan domain dev yang dipilih secara otomatis. Domain kustom memerlukan paket berbayar.
cloudflared menjalankan terowongan cepat dengan satu perintah jika Anda lebih suka Cloudflare.
cloudflared tunnel --url http://localhost:3000
Tempel URL publik yang dicetak oleh terowongan ke pengaturan webhook penyedia, dan peristiwa masuk akan mendarat di server lokal Anda. Untuk panduan lengkap pola ini, lihat cara menguji API localhost dengan layanan webhook.
3. Memicu peristiwa pengujian dari penyedia
URL penangkap hanya membantu setelah sesuatu dikirimkan kepadanya. Sebagian besar penyedia besar menyediakan alat untuk memicu peristiwa pengujian sesuai permintaan, sehingga Anda tidak perlu membuat pembayaran atau push yang nyata.
Stripe CLI adalah contoh paling bersih. Perintah stripe listen meneruskan peristiwa langsung dari sandbox Stripe Anda ke jalur lokal, dan mencetak secret tanda tangan webhook yang Anda masukkan ke konfigurasi aplikasi Anda.
# Meneruskan semua peristiwa ke penangan lokal Anda:
stripe listen --forward-to localhost:3000/webhooks
# Memfilter hanya untuk peristiwa tertentu:
stripe listen --events payment_intent.succeeded,checkout.session.completed \
--forward-to localhost:3000/webhooks
Dengan listener berjalan, stripe trigger memicu peristiwa pengujian. Perhatikan bahwa pemicuan menciptakan objek API yang didukung dengan benar dan memiliki efek samping: payment_intent.succeeded juga memancarkan payment_intent.created.
stripe trigger payment_intent.succeeded
stripe trigger checkout.session.completed
stripe trigger --help # mencantumkan setiap peristiwa yang didukung
GitHub menyimpan riwayat pengiriman singkat yang dapat Anda putar ulang. Buka repo Anda, lalu Pengaturan, lalu Webhook di bawah "Kode dan otomatisasi." Klik URL webhook, buka tab "Pengiriman terbaru", klik GUID pengiriman, dan klik "Kirim ulang." Dua batasan penting: Anda hanya dapat mengirim ulang pengiriman dari 3 hari terakhir, dan Anda memerlukan akses admin ke repo. GitHub tidak secara otomatis mengirim ulang pengiriman yang gagal, jadi pemutaran ulang dilakukan secara manual.
Webhook masuk Slack adalah yang paling sederhana untuk diuji. Anda mengirim pesan dengan melakukan POST JSON ke URL webhook. Payload minimal hanyalah bidang text.
curl -X POST https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX \
-H 'Content-type: application/json' \
-d '{"text":"Halo, dunia."}'
URL webhook Slack adalah rahasia. Slack mencabut URL yang bocor, jadi jauhkan dari kode sisi klien dan repositori publik.
4. Menegaskan penangan Anda
Penangkapan dan pemicuan membuktikan bahwa sistem berfungsi. Itu tidak membuktikan bahwa penangan Anda benar. Alat terakhir mengirimkan payload yang dibuat dengan cermat dan memeriksa respons serta efek samping. Pada dasarnya, itu adalah perintah curl dengan body representatif.
curl -X POST http://localhost:3000/webhooks \
-H 'Content-Type: application/json' \
-H 'Stripe-Signature: t=...,v1=...' \
-d '{"id":"evt_test","type":"payment_intent.succeeded","data":{"object":{"id":"pi_123","status":"succeeded"}}}'
Sebuah curl tunggal baik untuk uji asap. Itu kurang memadai ketika Anda menginginkan pengujian yang berulang dan ditegaskan yang berjalan di CI. Di situlah alat API khusus mendapatkan tempatnya.
Menguji webhook dengan Apidog
Apidog adalah platform API all-in-one untuk merancang, mendebug, menguji, melakukan mocking, dan mendokumentasikan API. Ia tidak memiliki "kotak masuk webhook" khusus, jadi bagian ini jujur tentang apa yang sebenarnya dilakukannya dengan baik: membuat payload, menyimpannya, menegaskan respons, dan menggantikan penyedia dengan server mock.
Buat dan simpan contoh payload sebagai permintaan yang dapat digunakan kembali
Ambil payload yang Anda tangkap dari webhook.site (atau disalin dari dokumen penyedia) dan bangun menjadi permintaan Apidog. Atur metode ke POST, tempel body JSON, dan tambahkan header yang dikirim penyedia, termasuk header tanda tangan yang diperiksa penangan Anda.
Simpan permintaan tersebut terhadap titik akhir Anda. Sekarang Anda memiliki cara yang berulang dan terkontrol versi untuk melakukan POST payload yang diketahui baik (atau yang sengaja salah bentuk) ke penangan Anda, alih-alih mengetik ulang perintah curl setiap kali.
Tegaskan respons dengan pembuat penegasan visual
Mengirim payload adalah setengah dari pengujian. Setengah lainnya adalah memeriksa apa yang dikembalikan penangan Anda. Di langkah permintaan atau skenario, buka Post Processors, klik "+ Tambahkan", dan pilih "Assertion." Apidog menambahkan aturan validasi yang Anda konfigurasi tanpa kode.
Arahkan penegasan ke body respons dan gunakan $ untuk root JSON. Misalnya, targetkan $.data.status, atur kondisi ke Equals, dan bandingkan dengan succeeded. Jalankan permintaan, dan hasilnya ditampilkan di tab Assertion. Penegasan visual membandingkan nilai sebagai string. Ketika Anda membutuhkan pemeriksaan tipe yang tepat (angka nyata, boolean), beralihlah ke skrip kustom menggunakan sintaks pm.test yang kompatibel dengan Postman.
Ini mengubah "itu mengembalikan 200" menjadi "itu mengembalikan 200, bidang status berhasil, dan ID pesanan cocok." Buat beberapa penegasan dalam satu skenario untuk mencakup jalur sukses, kasus bidang yang hilang, dan penolakan tanda tangan yang buruk.
Gunakan server mock untuk menggantikan penyedia
Terkadang Anda ingin menguji arah lain: layanan di tumpukan Anda yang memanggil penyedia. Selama pengujian lokal, Anda mungkin tidak ingin benar-benar mengenai penyedia. Server mock Apidog memungkinkan Anda menggantikannya.
Apidog menawarkan tiga jenis mock. Local Mock berjalan dengan klien desktop dan hanya berfungsi saat klien terbuka. Cloud Mock dihosting di server Apidog, berjalan 24/7, dan dapat dihidupkan atau dimatikan (mati secara default). Runner Mock berjalan di infrastruktur runner yang di-host sendiri dan dibagikan di seluruh tim Anda. Setiap titik akhir HTTP memiliki modul Mock; salin URL mock dari tab API dalam mode Desain atau tab Mock dalam mode Debug. Hanya jalur yang dimulai dengan / yang mengarahkan ke lingkungan mock. Arahkan kode Anda ke URL mock tersebut selama pengujian, dan integrasi Anda mendapatkan respons penyedia yang dapat diprediksi tanpa panggilan API nyata atau efek samping.
Jalankan pengujian webhook di CI dengan Apidog CLI
Setelah skenario Anda berhasil secara lokal, jalankan pada setiap push dengan Apidog CLI. Ini membutuhkan Node.js v16 atau yang lebih baru.
npm install -g apidog-cli
node -v && apidog -v && which node && which npm && which apidog # memverifikasi instalasi
Jalankan skenario tersimpan secara online, lewatkan token akses dan ID dari tab CI/CD "Command line" skenario tersebut.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -d 3497013 -r html,cli
Di sini -t adalah skenario pengujian, -e adalah lingkungan (wajib), -d adalah data pengujian (jalur file CSV atau JSON, atau ID kumpulan data yang disimpan), dan -r mengatur pelapor, yang menerima cli, html, json, dan junit. Untuk panduan baris perintah lengkap, lihat tutorial Apidog CLI.
Ingin membangun dan menegaskan pengujian webhook Anda sendiri secara visual? Coba Apidog gratis, tidak perlu kartu kredit.
Alur kerja pengujian webhook langkah demi langkah
Menyatukan alat-alatnya, berikut adalah urutan yang dapat diulang.
- Periksa payload nyata. Arahkan penyedia ke URL webhook.site dan tangkap satu peristiwa nyata. Perhatikan bentuk body, header, dan format tanda tangan.
- Jangkau kode Anda. Jalankan penangan Anda secara lokal, buka terowongan dengan
ngrok http 3000ataucloudflared, dan masukkan URL publik ke dalam konfigurasi webhook penyedia. - Memicu peristiwa nyata. Gunakan
stripe trigger, tombol Redeliver GitHub, atau POST Slack untuk mengirim peristiwa asli melalui terowongan. - Verifikasi penanganan tanda tangan. Kirim payload yang sama dengan tanda tangan yang valid dan lagi dengan yang diubah. Penangan Anda harus menerima yang pertama dan menolak yang kedua.
- Tegaskan respons dan efek samping. Simpan payload sebagai permintaan Apidog, tambahkan penegasan pada body dan status respons, dan konfirmasi baris basis data atau panggilan hilir terjadi.
- Otomatiskan. Pindahkan skenario ke Apidog CLI sehingga berjalan di CI pada setiap perubahan.
Jika Anda merancang sistem webhook itu sendiri daripada hanya mengonsumsinya, cara merancang webhook yang andal dan praktik terbaik webhook pembayaran mencakup percobaan ulang, idempoten, dan keamanan. Untuk gambaran yang lebih luas, panduan API webhook dan webhook dan arsitektur berbasis peristiwa menjelaskan di mana webhook cocok dalam sistem yang lebih besar.
Pertanyaan yang Sering Diajukan
Bagaimana cara menguji webhook?
Berikan URL yang dapat dijangkau kepada penyedia, picu peristiwa nyata atau pengujian, lalu konfirmasikan bahwa penangan Anda menerima payload, memverifikasi tanda tangan, mengembalikan status yang benar, dan melakukan efek samping yang diharapkan. Tangkap payload nyata terlebih dahulu, lalu buat permintaan berulang dengan penegasan sehingga pengujian berjalan dengan cara yang sama setiap saat.
Bagaimana cara menguji webhook secara lokal?
Jalankan penangan Anda pada port lokal, lalu ekspos dengan terowongan agar penyedia dapat menjangkau mesin Anda. Gunakan ngrok http 3000 atau cloudflared tunnel --url http://localhost:3000, tempel URL HTTPS publik ke pengaturan webhook penyedia, dan picu peristiwa. Permintaan masuk akan mendarat di server lokal Anda, tempat Anda dapat mengatur breakpoint dan memeriksanya secara langsung.
Bagaimana cara menguji webhook dengan Postman?
Postman dapat melakukan POST payload yang dibuat dengan cermat ke titik akhir Anda dan menegaskan respons, tetapi ia tidak dapat menerima webhook masuk yang nyata dengan sendirinya. Hal yang sama berlaku untuk Apidog: Anda membuat permintaan dengan payload dan header penyedia, menambahkan penegasan pada body dan status respons, dan menyimpannya sebagai pengujian yang dapat digunakan kembali. Untuk menangkap peristiwa masuk yang asli, pasangkan alat ini dengan layanan penangkap atau terowongan.
Bagaimana cara menguji webhook Stripe?
Gunakan Stripe CLI. Jalankan stripe listen --forward-to localhost:3000/webhooks untuk meneruskan peristiwa sandbox ke penangan Anda dan mendapatkan secret penandatanganan. Lalu jalankan stripe trigger payment_intent.succeeded (atau peristiwa apa pun dari stripe trigger --help) untuk memicu peristiwa pengujian nyata. Pemicuan menciptakan objek API yang didukung dan dapat berjenjang, sehingga payment_intent.succeeded juga memancarkan payment_intent.created.
Bagaimana cara menguji webhook Slack?
Lakukan POST JSON ke URL webhook masuk. Payload valid minimal adalah {"text":"Halo, dunia."}, dikirim dengan header Content-type: application/json. Pengujian yang berhasil akan memposting pesan ke saluran yang dikonfigurasi. Jaga kerahasiaan URL, karena Slack mencabut URL webhook yang bocor.
Bagaimana cara menguji URL webhook?
Kirim POST sampel ke URL dan konfirmasikan bahwa itu mengembalikan status sukses dan berperilaku dengan benar. Pemeriksaan tercepat adalah curl tunggal dengan body representatif. Untuk pengujian nyata, tangkap payload aktual terlebih dahulu, kirimkan dengan tanda tangan yang valid dan tidak valid, dan tegaskan respons serta efek samping daripada hanya memeriksa 200.