Retry dan pemulihan webhook
Ketika receiver tidak menerima event dengan sukses, Valcentra mencoba pengiriman kembali dengan jeda terbatas. Retry webhook tidak membuat payment baru dan tidak sama dengan retry request API Anda.
Bedakan dua arah retry
| Arah | Pihak yang mencoba ulang | Pengaman |
|---|---|---|
| Backend Anda → API create payment | Backend Anda | Key dan body operasi yang sama; lihat idempotensi. |
| Valcentra → receiver webhook | Valcentra | Receiver mendeduplikasi event.id dari body terverifikasi. |
Kapan delivery dianggap gagal?
Pengiriman dianggap berhasil jika receiver membalas HTTP 2xx dalam batas waktu. Respons non-2xx, gangguan jaringan, timeout, redirect, atau penolakan kebijakan URL dapat membuat delivery gagal. Batas waktu HTTP saat ini 5 detik.
Jika receiver sudah menyimpan event tetapi responsnya hilang, event dapat dikirim lagi. Itulah sebabnya deduplikasi diperlukan meskipun endpoint jarang mengalami error.
Jadwal percobaan saat ini
Satu delivery memiliki paling banyak 6 percobaan otomatis:
| Percobaan | Jeda setelah kegagalan sebelumnya |
|---|---|
| 1 | Dijadwalkan tanpa jeda retry awal. |
| 2 | 1 menit. |
| 3 | 5 menit. |
| 4 | 30 menit. |
| 5 | 2 jam. |
| 6 | 6 jam. |
Jeda ini relatif terhadap kegagalan percobaan sebelumnya, bukan semuanya dihitung dari pembuatan event. Waktu eksekusi aktual bergantung pada pemrosesan worker; jadwal bukan jaminan pengiriman tepat pada detik tertentu.
Membaca status delivery
| Status | Arti | Langkah Anda |
|---|---|---|
PENDING | Menunggu percobaan pertama atau pengiriman ulang. | Periksa endpoint aktif; tunggu pemrosesan. |
PROCESSING | Sedang dikirim. | Jangan memicu resend berulang. |
DELIVERED | Receiver membalas 2xx. | Periksa inbox/worker Anda jika pesanan belum berubah. |
FAILED | Percobaan gagal, masih dapat dijadwalkan ulang. | Perbaiki penyebab dan lihat jadwal berikutnya. |
EXHAUSTED | Retry otomatis berhenti atau event tidak dapat dikirim dengan aman. | Investigasi sebelum resend terkontrol. |
Pada detail delivery, periksa jumlah percobaan (attemptCount), jadwal berikutnya (availableAt), dan kategori kegagalan (lastError). Itu adalah informasi delivery, bukan status paid atau failed dari payment.
Perbaiki receiver sebelum resend
- Buka detail delivery di project dan environment yang benar.
- Periksa apakah URL dapat dijangkau tanpa redirect, endpoint aktif, dan secret sesuai.
- Untuk
TIMEOUT, pindahkan pekerjaan lambat ke worker setelah event tersimpan persisten. - Untuk
HTTP_ERROR, periksa respons receiver dan log kategori kegagalan tanpa secret atau raw payload. - Pastikan receiver tetap mendeduplikasi event dan pemenuhan pesanan.
- Untuk delivery
FAILEDatauEXHAUSTED, gunakan aksi resend yang tersedia sesuai izin, bukan mengirim ulang create payment.
Resend memakai event ID dan snapshot yang sama. Receiver boleh membalas 2xx tanpa proses bisnis ulang jika event itu sudah diterima aman. Jangan melonggarkan pemeriksaan signature untuk menerima event yang dikirim ulang; timestamp delivery akan ditandatangani kembali.
Jika event tidak dapat dipulihkan
Kategori seperti PUBLIC_SNAPSHOT_UNAVAILABLE atau PUBLIC_SNAPSHOT_INVALID membutuhkan bantuan operator. Jangan merekonstruksi event lama dari data payment terbaru atau mengedit database keuangan langsung.
Jika ada kesenjangan status pada sistem merchant, ambil payment terbaru melalui API dan lakukan rekonsiliasi pesanan secara terkontrol. Proses ini juga harus mencegah pemenuhan ganda.
Lanjutkan ke: checklist sandbox untuk menguji receiver, atau verifikasi signature jika delivery gagal akibat validasi keamanan.