Siklus Hidup Pesan dan Idempotensi

Pakai panduan ini untuk membangun integrasi yang aman dari pengulangan (retry-safe).

Siklus hidup pesan

Alur status yang khas:

queued -> sent -> delivered -> read
   \-> failed

• queued: diterima dan menunggu pengiriman.
• sent: diserahkan ke penyedia (provider).
• delivered: dikirim ke perangkat penerima/status penyedia.
• read: tanda terima telah dibaca terpantau.
• failed: pengiriman gagal atau ditolak oleh penyedia.

Batasan pengulangan (Retry boundaries)

1. Ulangi hanya pada kesalahan 429 dan 5xx.
2. Jangan mengulangi kegagalan validasi (400, 422) sebelum memperbaiki isi permintaan (payload).
3. Pakai penundaan eksponensial (exponential backoff) terbatas dengan jitter.

Pola idempotensi klien

• Buat kunci operasi (operation key) di aplikasi kamu per maksud pengiriman.
• Simpan pemetaan operation_key -> message_id.
• Jika operasi yang sama diulangi, kembalikan message_id yang ada dari penyimpanan kamu.

Pola deduplikasi webhook

Pakai ID pengiriman dari header webhook (svix-id atau webhook-id) untuk menghindari pemrosesan ganda:

jika delivery_id sudah diproses:
  kembalikan 200
simpan delivery_id
antrekan pemrosesan
kembalikan 200

Untuk message.new / message.status_update, jadikan juga message_id di dalam isi JSON sebagai kunci logika bisnis.

Alur rekonsiliasi

Halaman terkait

• Kirim pesan
• Webhook