Webhooks dan SDKs
Webhooks beri tahu backend Anda tentang acara bisnis. Gunakan data tersebut bersama dengan kueri API sehingga pengiriman yang tertunda atau hilang tidak menyebabkan catatan Anda tidak terselesaikan.
Verifikasi sebelum diproses
Pengiriman saat ini mencakup X-Webhook-Signature dan X-Webhook-Timestamp. Tanda tangan menggunakan HMAC-SHA256 di atas teks header stempel waktu, titik, dan isi permintaan mentah yang tepat. Nilai headernya berbentuk sha256=<HEX_SIGNATURE>.
- Pertahankan isi mentah sebelum diurai JSON.
- Validasi stempel waktu menggunakan toleransi jam yang disepakati.
- Verifikasi tanda tangan dengan rahasia webhook menggunakan perbandingan waktu konstan.
- Baru kemudian tafsirkan payload dan perbarui catatan bisnis.
Memformat ulang JSON yang diurai sebelum verifikasi mengubah byte yang ditandatangani. Verifikasi Webhook menggunakan rahasia webhook, bukan rahasia permintaan API atau kunci otorisasi pelanggan.
Simpan dan hapus duplikatnya
Amplop berisi event_id, event_type, created_at, tenant_id dan data. Untuk pengiriman peristiwa normal, gunakan identitas peristiwa terverifikasi dengan titik akhir atau konteks ruang kerja Anda untuk mencegah penerapan berulang. Pertahankan keputusan tersebut secara atomik dengan pembaruan bisnis yang dihasilkan, atau antrikan peristiwa terverifikasi secara tahan lama sebelum mengonfirmasinya.
X-Webhook-Idempotency-Key juga disediakan untuk pengiriman kotak keluar normal. Ini adalah metadata pengiriman, bukan bidang muatan yang ditandatangani secara independen. Jangan biarkan perubahan tajuk menyebabkan peristiwa terverifikasi yang sama memindahkan uang dua kali. Pengiriman pengujian dan operasi manual mungkin memiliki pengidentifikasi berbeda atau menghilangkan header ini.
Kembalikan respons yang berhasil setelah menerima acara tersebut dalam jangka waktu lama. Desain untuk duplikat dan acara yang tertunda atau rusak. Stempel waktu pengiriman bukan merupakan jaminan waktu terjadinya bisnis. Kueri sumber daya yang mendasarinya ketika suatu peristiwa bertentangan dengan hasil yang diketahui kemudian.
Pilih paket integrasi
Ini adalah cakupan implementasi sumber, bukan konfirmasi ketersediaan registri paket atau rilis umum. Dapatkan paket yang sesuai versi dan instruksi instalasinya selama orientasi. Sumber daya lain mungkin memerlukan panggilan langsung API; jangan menyimpulkan klien API penuh dari keberadaan paket webhook.
Uji jalur penerimaan
Uji pengiriman yang valid, isi yang dimodifikasi, tanda tangan tidak valid, stempel waktu basi, peristiwa duplikat, dan restart penerima. Konfirmasikan pengaturan percobaan ulang dan pemutaran ulang dengan lingkungan integrasi. Callback yang hilang seharusnya memicu rekonsiliasi, bukan permintaan penarikan kedua.