Perbandingan · Terbit
Satu endpoint webhook atau beberapa: anggaran percobaan ulang yang berpindah pemilik begitu penerusan dikerjakan sendiri, secret yang bisa dirotasi tanpa menyeret sistem lain, dan urutan antar sistem yang hanya ada pada salah satu bentuknya
Integrasi hampir selalu dimulai dengan satu endpoint webhook, karena pada awalnya memang hanya satu sistem yang perlu tahu bahwa pembayaran sudah masuk. Lalu muncul sistem kedua: pencatatan keuangan, gudang, papan pantau penjualan, atau pemberitahuan ke grup. Di titik itu ada dua jalan, dan keduanya jarang dibandingkan dengan sengaja.
Jalan pertama: endpoint yang sudah ada meneruskan sendiri ke sistem kedua. Jalan kedua: sistem kedua mendapat endpoint-nya sendiri, karena satu akun boleh memasang sampai lima endpoint per mode, masing-masing dengan URL, nama dan signing secret sendiri.
Jawaban singkatnya, dan sisa halaman ini adalah alasannya: yang berpindah antara kedua bentuk itu bukan jumlah kode yang ditulis, melainkan siapa yang menanggung percobaan ulang saat sistem kedua sedang mati. Kasera Pay mencoba ulang tiap endpoint sampai tujuh kali dalam kisaran 33 jam, sendiri-sendiri. Penerusan yang dikerjakan di dalam handler sendiri tidak mewarisi tangga itu sama sekali.
Yang sebenarnya dibandingkan
Pembandingnya bukan “satu webhook melawan banyak webhook”, karena event yang dikirim sama saja: satu payment.paid per pembayaran yang terkonfirmasi, dengan id yang sama di setiap salinan. Yang dibandingkan adalah letak percabangannya. Pada bentuk pertama percabangan ada di dalam kode penjual, sesudah batas yang diverifikasi. Pada bentuk kedua percabangan ada di daftar endpoint, sebelum batas itu, dan tiap cabang adalah pengiriman yang berdiri sendiri lengkap dengan tanda tangan, percobaan ulang dan barisan log-nya sendiri.
Keputusan dasar sebelum ini, yaitu memakai webhook atau menanyakan status secara berkala, dibahas terpisah di perbandingan webhook dan polling. Halaman ini mengandaikan webhook sudah dipilih.
Anggaran percobaan ulang, dan siapa yang memilikinya
Ini bagian yang menentukan, dan bisa dinyatakan dalam satu keadaan konkret: pembayaran masuk pukul dua pagi, toko sehat, sistem pencatatan keuangan sedang mati karena pemeliharaan sampai pukul delapan.
Pada bentuk penerusan sendiri, handler toko menerima event, memverifikasi tanda tangannya, menyimpan pesanannya, lalu mencoba meneruskan ke pencatatan dan gagal. Sesudah itu ada dua pilihan yang sama-sama tidak nyaman. Menjawab 2xx berarti menyatakan event sudah selesai diproses: dari sisi Kasera Pay pengiriman itu berstatus terkirim, tidak akan pernah dikirim lagi, dan selisihnya menjadi milik penjual sepenuhnya. Menjawab selain 2xx memang memicu percobaan ulang, tetapi percobaan ulang itu membawa seluruh event, sehingga toko menerima pesanan yang sama untuk kedua kalinya dan hanya dedupe berdasarkan id yang menyelamatkannya. Pada pemeliharaan enam jam, menolak berulang kali memang bisa menutup selisihnya. Pada pemadaman yang melewati kisaran 33 jam, tangga tujuh percobaannya habis dan tidak ada apa pun yang tersisa untuk dicoba ulang, sehingga selisihnya kembali menjadi milik penjual.
Pada bentuk dua endpoint, pukul dua pagi itu menghasilkan dua pengiriman terpisah. Toko menjawab 2xx dan selesai. Pencatatan tidak menjawab, lalu dicoba ulang dengan jeda yang melebar, memakai tangganya sendiri, tanpa menyentuh toko sama sekali. Kalau pemeliharaan selesai dalam rentang itu, event masuk tanpa ada yang perlu dikerjakan. Ada cara yang lebih rapi lagi kalau pemadamannya direncanakan: endpoint yang dinonaktifkan menahan event-nya tanpa membakar satu pun percobaan ulang sampai diaktifkan kembali, sehingga pemeliharaan enam jam tidak memakan jatah apa pun.
Satu hal yang tidak berubah pada kedua bentuk: pengiriman bersifat at-least-once, jadi id event tetap satu-satunya penjamin. Sebab kenapa pembayaran bisa terbaca dua kali dan cara menutupnya dibahas di tulisan tentang pembayaran yang masuk dua kali.
Perbandingan per dimensi
| Dimensi | Satu endpoint, penerusan sendiri | Beberapa endpoint |
|---|---|---|
| Percobaan ulang ke sistem kedua | Tidak ada, kecuali dibangun sendiri | Tujuh percobaan dalam kisaran 33 jam, per endpoint |
| Sistem kedua mati | Selisihnya jadi milik penjual | Menyusul sendiri saat hidup lagi |
| Tempat verifikasi tanda tangan | Satu | Sebanyak endpoint-nya |
| Rotasi secret | Menyentuh semua sistem sekaligus | Per endpoint, satu sistem saja |
| Urutan antar sistem | Bisa dipastikan berurutan | Tidak dijamin sama sekali |
| Log pengiriman | Berhenti di batas penjual | Terbaca per endpoint sampai ujung |
| Batas jumlah | Tidak relevan | Lima per mode |
Secret yang berdiri sendiri, dan rotasi yang tidak menyeret sistem lain
Tiap endpoint punya signing secret sendiri, dan rotasi berlaku pada satu endpoint saja. Akibatnya nyata saat sebuah secret perlu diganti karena bocor, karena orang yang memegangnya keluar, atau karena penyedia sistem pihak ketiga berganti. Pada bentuk endpoint tunggal, rotasi menyentuh satu-satunya batas yang dimiliki integrasi, sehingga seluruh sistem di belakangnya bergantung pada satu deploy yang benar. Pada bentuk beberapa endpoint, secret sistem gudang bisa dirotasi tanpa toko mengetahuinya.
Rotasi punya masa tenggang 24 jam yang membuat header membawa dua tanda tangan sekaligus, dan verifikasi yang hanya membaca entri pertama akan patah tanpa satu pun pesan galat. Urutan operasinya, beserta ekor percobaan ulang yang lebih panjang daripada masa tenggang itu, ada di panduan merotasi signing secret.
Biaya sebenarnya dari beberapa endpoint: pekerjaan verifikasi yang berlipat
Bagian ini sering hilang dari pembahasan, dan inilah yang membuat endpoint tunggal tetap menjadi pilihan yang benar untuk banyak integrasi. Setiap endpoint adalah sebuah batas publik yang harus dikerjakan dengan benar: URL wajib https dan mengarah ke alamat publik, tanda tangan Kasera-Signature-V1 wajib diverifikasi sebagai HMAC-SHA256 atas t disambung titik disambung raw body, pengiriman dengan timestamp yang melenceng lebih dari lima menit wajib ditolak, dan event yang sudah pernah diproses wajib dikenali dari id-nya. Rinciannya beserta contoh kode ada di dokumentasi webhook.
Lima endpoint berarti daftar itu dikerjakan lima kali, di lima basis kode yang mungkin dipegang orang berbeda. Penerusan di belakang satu endpoint tidak menuntut apa pun dari daftar itu, karena lalu lintasnya internal dan tidak perlu ditandatangani. Jadi perbandingan yang sesungguhnya adalah ketangguhan terhadap sistem yang mati melawan luas permukaan yang bisa salah, dan jawabannya bergantung pada siapa yang memegang sistem kedua: sistem pihak ketiga yang sudah bisa memverifikasi webhook lebih baik diberi endpoint sendiri, sementara skrip internal buatan sendiri lebih baik diletakkan di belakang endpoint yang sudah ada.
Urutan antar sistem, yang hanya ada pada satu bentuk
Beberapa endpoint tidak menjamin urutan apa pun di antara mereka. Kalau pencatatan keuangan tidak boleh melihat sebuah pembayaran sebelum baris pesanannya ada di toko, urutan itu hanya bisa dipastikan pada bentuk endpoint tunggal, karena di situ penerusan berjalan sesudah penyimpanan pesanan selesai. Pada dua endpoint yang berdiri sendiri, pencatatan bisa menerima event lebih dulu daripada toko, dan sistem yang mengandaikan sebaliknya akan gagal secara tidak menentu, yaitu jenis kegagalan yang paling mahal dicari.
Pertanyaan pemilahnya satu kalimat: apakah sistem kedua membutuhkan sesuatu yang baru dibuat oleh sistem pertama. Papan pantau yang cukup menghitung nominal, atau pemberitahuan yang hanya mengirim pesan, tidak membutuhkannya, dan endpoint terpisah adalah pilihan yang lebih murah untuk keduanya.
Yang terbaca di log, dan yang tidak
Log pengiriman di dashboard mencatat status per pengiriman, yaitu terkirim, sedang dicoba ulang, gagal, habis percobaan, dan satu status khusus untuk event yang tidak punya endpoint tujuan sama sekali. Tiap baris menyebut endpoint mana yang dimaksud, dan ada ringkasan tingkat keberhasilan untuk rentang waktu terakhir.
Akibatnya pada pilihan ini jelas. Dengan endpoint terpisah, kegagalan pengiriman ke pencatatan keuangan terbaca di log Kasera Pay sebagai barisnya sendiri. Dengan penerusan sendiri, log Kasera Pay menyatakan pengiriman berhasil dan memang benar, sementara kegagalan penerusan ke sistem kedua tidak terlihat di sana sama sekali dan harus dipantau oleh penjual. Cara membaca log itu saat sebuah event tidak sampai dibahas di tulisan tentang webhook yang tidak sampai.
Batas yang nyata, dan mode yang benar-benar terpisah
Batasnya lima endpoint per mode, dan mode live serta mode tes adalah dua daftar berbeda dengan secret berbeda: event mode tes hanya pernah sampai ke endpoint mode tes, dan secret tes tidak akan pernah bisa memverifikasi payload live. Jumlah endpoint karena itu tidak perlu sama antara kedua mode.
Aturan memilih
- Sistem kedua dipegang pihak lain dan sudah bisa memverifikasi webhook: beri endpoint sendiri.
- Sistem kedua tidak boleh tertinggal walau mati semalam: beri endpoint sendiri, karena tangga percobaan ulangnya yang menutup selisihnya.
- Sistem kedua membutuhkan data yang baru dibuat sistem pertama: tetap satu endpoint, teruskan berurutan.
- Sistem kedua adalah skrip internal yang gagalnya tidak berakibat pada uang: tetap satu endpoint, karena menambah batas publik tidak sepadan.
- Ragu: mulai dari satu endpoint. Menambah endpoint kedua belakangan tidak mengubah secret yang sudah dipakai dan tidak menuntut perubahan apa pun pada handler pertama.
Pertanyaan yang sering muncul
Berapa endpoint webhook yang boleh dipasang satu akun?
Lima per mode, jadi lima untuk mode live dan lima lagi untuk mode tes, masing-masing dengan URL, nama dan signing secret sendiri. Saat jumlahnya sudah lima, kolom penambahan tetap terlihat dalam keadaan nonaktif beserta keterangan jumlah yang terpakai, bukan hilang dari halaman.
Apakah event yang sama dikirim beberapa kali kalau ada beberapa endpoint?
Setiap endpoint yang aktif menerima salinannya sendiri, dan salinan itu membawa id event yang sama. Jadi bukan satu pengiriman yang dibagi, melainkan beberapa pengiriman dengan id yang identik, masing-masing dengan tangga percobaan ulangnya sendiri. Karena pengiriman bersifat at-least-once, dedupe berdasarkan id event tetap wajib pada setiap penerima, sama wajibnya seperti pada integrasi berendpoint tunggal.
Kalau satu endpoint mati, apakah endpoint yang lain ikut tertunda?
Tidak. Tiap endpoint dicoba ulang sendiri-sendiri, jadi endpoint yang menolak atau mati tidak menahan pengiriman ke endpoint lain dan tidak memakai jatah percobaan milik endpoint lain. Inilah satu-satunya perbedaan yang tidak bisa ditiru oleh penerusan sendiri: pada bentuk endpoint tunggal, sistem kedua yang mati harus ditangani oleh kode penjual, karena dari sisi Kasera Pay event itu sudah selesai terkirim.
Apakah menambah endpoint kedua mengubah signing secret yang sudah dipakai?
Tidak. Endpoint baru datang dengan secret-nya sendiri, dan secret endpoint yang sudah ada hanya berubah kalau dirotasi dengan sengaja. Menyimpan URL atau mengganti nama endpoint juga tidak menyentuh secret-nya, sehingga memindahkan endpoint ke domain baru tidak menuntut deploy ulang kode verifikasi. Endpoint bahkan bisa ditambahkan tanpa URL lebih dulu, semata untuk mengambil secret-nya, lalu domainnya diarahkan setelah handler-nya siap.
Mana yang lebih aman, satu endpoint atau beberapa?
Keduanya sama amannya di jalur Kasera Pay, karena tiap pengiriman ditandatangani dengan secret endpoint tujuannya. Yang berbeda adalah jumlah tempat yang bisa salah menerapkan verifikasi: satu endpoint berarti satu batas yang diverifikasi dengan penerusan internal di belakangnya, sementara lima endpoint berarti lima tempat yang masing-masing harus memverifikasi HMAC atas raw body, menolak timestamp yang melenceng lebih dari lima menit, dan dedupe berdasarkan id.
Ringkasnya
- Lima endpoint per mode, masing-masing dengan URL, nama dan signing secret sendiri, dan masing-masing menerima salinan event dengan id yang sama.
- Perbedaan yang menentukan adalah anggaran percobaan ulang: tujuh percobaan dalam kisaran 33 jam berlaku per endpoint, sementara penerusan yang dikerjakan sendiri tidak mewarisi tangga itu.
- Jawaban 2xx adalah pengakuan bahwa event sudah selesai, jadi meneruskan sendiri lalu gagal berarti selisihnya menjadi milik penjual.
- Endpoint terpisah membuat rotasi secret dan pembacaan log berjalan per sistem, dengan harga pekerjaan verifikasi yang berlipat sebanyak endpoint-nya.
- Urutan antar sistem tidak dijamin di antara endpoint yang berdiri sendiri, sehingga sistem yang bergantung pada hasil sistem lain tetap diletakkan di belakang satu endpoint.
