Webhook & background job
Batas server-to-server untuk callback provider dan rekonsiliasi. Ini bukan webhook pelanggan atau API yang boleh dipanggil langsung dari browser.
Unduh OpenAPI 3.1Di halaman ini
Masuk dari provider, bukan keluar ke pelanggan
Ping! menerima callback Tiger SMS dan KlikQRIS untuk memperbarui transaksi internal. Belum ada endpoint untuk mendaftarkan URL webhook pelanggan, memilih event, atau menerima event reseller. Jangan menganggap endpoint callback sebagai API publik.
| Endpoint | Autentikasi | Peran |
|---|---|---|
| POST /api/webhooks/tiger | X-Signature: hex HMAC-SHA256 atas raw body, dengan TIGER_WEBHOOK_SECRET. | Menerima segmen SMS untuk aktivasi yang dikenal. |
| POST /api/webhooks/klikqris | Signature per transaksi yang sudah tersimpan, plus kecocokan referensi/amount/total. | Konfirmasi pembayaran dan settlement deposit. |
| GET /api/cron/orders/reconcile | Authorization: Bearer CRON_SECRET, dibandingkan secara timing-safe. | Rekonsiliasi order tertunda dalam batch terbatas. |
Tiger: verifikasi bytes asli
- Route mensyaratkan JSON dan membatasi body hingga 32.768 byte. Signature diverifikasi sebelum pemrosesan payload.
- HMAC dihitung atas raw body. Mengubah whitespace atau men-serialize ulang JSON sebelum verifikasi mengubah signature.
- Callback membawa SMS, bukan semua perubahan status provider. Aktivasi yang belum siap dapat menghasilkan 503 dengan RECONCILIATION_REQUIRED agar provider mengirim ulang.
- Polling dan scheduler tetap diperlukan. Jangan menonaktifkannya hanya karena webhook sudah tersambung.
Implementasi: app/api/webhooks/tiger/route.ts, lib/providers/tiger/webhook.ts, dan lib/orders/webhook.ts. Jangan log raw callback karena berisi OTP.
KlikQRIS: signature bukan HMAC
- Body JSON dibatasi hingga 16.384 byte. Callback divalidasi dengan schema provider sebelum diproses.
- Signature adalah shared secret per transaksi dari respons pembuatan, bukan hash body. Bandingkan dengan nilai yang sudah disimpan.
- Cocokkan referensi transaksi, nominal, dan total. Jangan mempercayai signature yang pertama kali terlihat pada callback.
- Jika create belum commit, PAYMENT_NOT_READY / 503 meminta redelivery. Deposit PAID dilindungi kunci ledger tetap dan transaksi database agar hanya diterapkan sekali.
Implementasi: app/api/webhooks/klikqris/route.ts, lib/providers/klikqris/client.ts, dan lib/payments/service.ts.
Rekonsiliasi adalah bagian dari kebenaran transaksi
Script scripts/reconcile-loop.mjs pada jalur EC2 memanggil route rekonsiliasi setiap 60 detik. Konfigurasikan CRON_SECRET hanya di server/scheduler. Secret tidak terpasang atau provider belum disiapkan menghasilkan 503; otorisasi salah menghasilkan 401.
Bearer di route ini adalah kredensial operasional, bukan API key pelanggan. Jangan menaruhnya di NEXT_PUBLIC_, contoh request browser, atau unduhan OpenAPI pelanggan.
Acknowledgement dan redelivery
{
"ok": true,
"data": { "accepted": true }
}Tidak ada endpoint mock callback di halaman docs. Pengujian signature dan redelivery dijalankan oleh suite terisolasi; jangan mengirim callback palsu ke pembayaran atau order produksi.