Menangani Pengiriman Webhook

Respons cepat, dengan 2xx

Endpoint Anda harus merespons dengan status 2xx. Selain itu — 4xx, 5xx, atau server Anda timeout — dianggap gagal dan diantre untuk dicoba ulang.

Respons segera setelah Anda mencatat event secara durable; lakukan pekerjaan sebenarnya (update order, kirim email konfirmasi) setelah merespons, atau di background job. Handler yang lambat merespons berisiko dicoba ulang padahal sebenarnya akan berhasil kalau diberi waktu.

Retry

Pengiriman yang gagal dicoba ulang dengan exponential backoff — mulai dari 1 menit, berlipat ganda tiap kali, dibatasi maksimal 1 jam — sampai berhasil. Tidak ada jumlah percobaan tetap di mana Baiyar menyerah; ia terus mencoba ulang pada interval 1 jam tanpa batas sampai endpoint Anda mengembalikan 2xx.

Buat handler Anda idempotent

Karena adanya retry, endpoint Anda akan menerima event yang sama lebih dari sekali dalam operasi normal — bukan cuma kasus tepi. Gunakan id event untuk deduplikasi: catat ID mana yang sudah Anda proses, dan lewati (sambil tetap merespons 2xx) kalau melihatnya lagi.

Perhatian

Jangan mengandalkan data.id (ID transaksi/payment) untuk deduplikasi — percobaan ulang setelah payment.failed bisa menghasilkan transaksi baru, tapi pengiriman ulang dari event yang sama selalu membawa id event yang sama juga.

Menguji sebelum go live

Gunakan simulator payment sandbox untuk memicu pengiriman payment.paid / payment.failed secara end-to-end, tanpa provider bank/QRIS asli — baik dari Alat simulasi sandbox di halaman checkout (lihat Payment Links), atau langsung lewat POST /sandbox/payments/{providerPaymentID}/simulate. Ini cara tercepat untuk memastikan endpoint Anda merespons 2xx dan verifikasi signature Anda lolos, sebelum pembayaran pelanggan sungguhan bergantung padanya.

Selanjutnya

Verifikasi Signature Webhook — pastikan request benar-benar dari Baiyar sebelum Anda memprosesnya.