Apa itu idempotensi, dan bagaimana cara menangani webhook duplikat?

Koneksi yang terputus dapat membuat Anda tidak yakin apakah permintaan pengiriman berhasil. Acknowledgment yang hilang juga dapat menyebabkan pengirim webhook mengirimkan event yang sudah disimpan aplikasi Anda.

Kegagalan ini terjadi dari arah yang berlawanan. Bird dapat mengenali permintaan API yang diulang menggunakan kunci yang Anda berikan. Penerima webhook Anda memerlukan catatannya sendiri tentang event yang sudah diterima.

Bagaimana cara mencoba ulang pengiriman dengan aman?

Gunakan kembali header Idempotency-Key yang sama untuk setiap percobaan dari satu operasi logis API.

Anda memilih kunci, maksimal 255 karakter, dan mempertahankannya di setiap percobaan ulang. Nilai stabil seperti welcome-user/usr_abc123 dapat mengidentifikasi satu operasi welcome-message setelah proses Anda dimulai ulang.

Header ini berlaku untuk permintaan yang mengubah data seperti POST, PATCH, dan DELETE. Permintaan tanpa kunci diproses tanpa deduplikasi ini. GET mengabaikan header ini karena membaca resource sudah aman untuk diulang.

Bird mengembalikan respons tersimpan untuk permintaan yang cocok dan sudah selesai, termasuk status dan body aslinya. Respons tersebut membawa Idempotency-Replay: true, sehingga Anda dapat mengidentifikasi penggunaan ulang itu di log Anda.

Panduan idempotensi mendokumentasikan jendela respons selesai selama tiga jam secara default. Percobaan ulang setelah jendela itu berakhir dapat berjalan sebagai operasi baru. Jangan mengandalkan kunci itu secara permanen untuk mencegah pengiriman duplikat.

SDK Bird menghasilkan kunci untuk mutasi dan menggunakannya kembali di seluruh percobaan ulang internalnya. Bird CLI juga menghasilkan kunci untuk permintaan yang mengubah data jika tidak ada kunci. Tetapkan --idempotency-key secara eksplisit jika pemanggilan perintah terpisah harus berbagi operasi yang sama.

Untuk pengiriman SMTP, gunakan header pesan X-Bird-Idempotency-Key. Ini memungkinkan pengiriman ulang mengidentifikasi operasi yang sama.

Apa yang terjadi jika saya menggunakan kembali kunci secara salah?

Bird menolak penggunaan kunci yang bertentangan alih-alih mengembalikan respons untuk operasi yang berbeda.

Perbandingan mencakup method, endpoint, parameter path, query string, dan body. Untuk JSON, mengubah spasi berarti mengubah identitas permintaan, jadi pertahankan body asli saat mencoba ulang.

Kunci pada operasi yang belum selesai kedaluwarsa dalam tiga puluh detik. Batas ini memungkinkan permintaan lain melanjutkan setelah operasi yang ditinggalkan. Ini tidak menentukan apakah efek samping sudah terjadi.

Bird tidak menyimpan respons 5xx untuk diputar ulang. Coba ulang kesalahan server atau timeout dengan kunci yang sama agar respons sukses yang tercatat masih dapat digunakan kembali.

Penolakan validasi atau aturan bisnis melepaskan kunci. Anda dapat memperbaiki permintaan yang ditolak itu dan mencoba ulang dengan kunci yang sama karena tidak ada respons selesai yang disimpan.

Mengapa saya menerima webhook yang sama dua kali?

Bird dapat mencoba ulang event yang sudah disimpan penerima Anda jika tidak menerima respons sukses.

Penerima dapat menyimpan event sesaat sebelum koneksinya terputus. Bird tidak melihat acknowledgment sukses dan mencoba ulang, meskipun penerima sudah memiliki event tersebut.

Setiap percobaan ulang mempertahankan header webhook-id yang sama, yang mengidentifikasi event. Pemutaran ulang pengiriman yang terlewat juga mempertahankan identifier tersebut, sehingga keduanya dapat dikenali sebagai event yang sama.

Bagaimana cara membuat handler saya idempoten?

Simpan setiap webhook-id dengan constraint unik di database sebelum menjadwalkan pekerjaan event tersebut.

Memeriksa baris yang sudah ada sebelum menyisipkan menyisakan celah race condition: dua permintaan bersamaan bisa sama-sama tidak melihat baris. Biarkan database yang menolak identifier duplikat.

Simpan identifier dan job dalam transaksi yang sama. Ini mencegah identifier tercatat tanpa pekerjaan yang diantrekan.

1. Verifikasi permintaan, lalu sisipkan identifier dan job-nya dalam transaksi yang sama.
2. Kembalikan 2xx setelah transaksi itu di-commit, agar Bird dapat berhenti mencoba ulang.
3. Proses job yang tersimpan di worker yang dapat mengulangi tindakannya sendiri dengan aman.

Untuk identifier duplikat yang sudah di-commit, kembalikan sukses tanpa membuat job lain. Untuk transaksi yang gagal, kembalikan error agar Bird mencoba ulang.

Jauhkan pekerjaan berat dari penerima karena menunggunya dapat menyebabkan permintaan timeout. Worker dapat mencoba ulang karena alasan yang tidak terkait pengiriman webhook, jadi melindungi penerima saja tidak cukup.

Event juga dapat tiba tidak berurutan. Bandingkan waktu event di timestamp sebelum menimpa state yang lebih baru. Percobaan ulang webhook gagal mencakup contoh biaya parsial.

Apa yang tidak boleh saya andalkan?

Jangan berasumsi bahwa deduplikasi permintaan membuat efek samping duplikat mustahil terjadi.

Jika penyimpanan deduplikasi Bird tidak tersedia, permintaan tetap diproses tanpanya. Pertahankan pengaman di level bisnis jika mengulangi tindakan akan berbahaya.

Demikian pula, webhook-id membedakan pengiriman berulang dari satu event. Event terpisah memiliki identifier terpisah. Aplikasi Anda tetap menentukan apakah event tersebut membenarkan pengulangan tindakan yang sama.

Idempotensi mendokumentasikan perilaku percobaan ulang API. Webhook membahas jaminan pengiriman terpisah yang ditangani penerima Anda.