Webhook#

Webhook adalah cara Reader mengabari sistem Anda bahwa tagihan lunas, payout terkirim, atau ada kejadian lain. Reader mengirim POST berisi JSON ke callback_url aplikasi Anda, lalu menunggu balasan ack.

Halaman ini memuat semua aturan pengiriman. Contoh kode lengkap ada di Contoh kode.

Ringkasan dalam 30 detik#

1. Terima POST di callback_url.
2. Verifikasi X-Reader-Signature dari body mentah, dengan toleransi waktu 5 menit.
3. Cek event_id. Bila sudah pernah diproses, balas duplicate.
4. Proses event secepatnya. Pekerjaan berat dipindah ke antrean.
5. Dalam 10 detik, balas HTTP 2xx dengan:

{ "event_id": "evt_01j8zqa2b3c4d5e6f7g8h9j0km", "status": "accepted" }

Balasan 200 tanpa ack yang benar dianggap gagal dan dikirim ulang.

Menyiapkan endpoint#

Atur di dashboard, menu Aplikasi:

Satu aplikasi punya satu callback URL. Event dari kunci uji dan kunci live dikirim ke URL yang sama, dibedakan oleh field test.

Katalog event#

Balas accepted untuk jenis event yang tidak Anda kenal, supaya integrasi Anda tetap berjalan bila kelak ada jenis event baru.

Bentuk request#

POST <callback_url>
Content-Type: application/json
User-Agent: RAGH-Reader-Webhook/1.0
X-Reader-Event-Id: evt_01j8zqa2b3c4d5e6f7g8h9j0km
X-Reader-Timestamp: 1790566265
X-Reader-Signature: sha256=5f2b9c…

Body selalu berbentuk amplop yang sama:

{
  "event": "payment.paid",
  "event_id": "evt_01j8zqa2b3c4d5e6f7g8h9j0km",
  "api_version": "2026-09-28",
  "created_at": "2026-09-28T10:31:05+07:00",
  "test": false,
  "data": { }
}

Body sebuah event sama persis di setiap percobaan kirim. Yang berubah hanya header timestamp dan tanda tangan.

Isi data per event#

mutation, duplicate_mutation, dan reversal_mutation adalah ringkasan mutasi:

{
  "id": "mut_01j8zqb7r2s3t4v5w6x7y8z9a0",
  "counterparty_name": "BUDI SANTOSO",
  "transaction_at": "2026-09-28T10:31:00+07:00",
  "received_at": "2026-09-28T10:31:04+07:00"
}

Pada payment.paid dan payout.sent yang ditandai manual dari dashboard, mutation bernilai null.

Contoh lengkap payment.paid:

{
  "event": "payment.paid",
  "event_id": "evt_01j8zqa2b3c4d5e6f7g8h9j0km",
  "api_version": "2026-09-28",
  "created_at": "2026-09-28T10:31:05+07:00",
  "test": false,
  "data": {
    "id": "pay_01j8zq5v3m7c2k9x4h6t1r0bna",
    "tx_number": "TKO-260928-0042",
    "reference_id": "ORDER-123",
    "amount": 200000,
    "unique_code": 123,
    "total_amount": 200123,
    "bank": { "code": "BCA", "name": "BCA", "account_number": "1234567890", "account_holder": "PT CONTOH JAYA" },
    "status": "paid",
    "confirmation_delayed": false,
    "late": false,
    "paid_after_cancel": false,
    "match_type": "auto",
    "test": false,
    "description": "Kursus A",
    "customer": { "ref": "CUST-9", "name": "Budi", "contact": "081234567890" },
    "tags": ["produk:kursus-a", "kanal:instagram"],
    "metadata": { "cart_id": "C-77" },
    "expires_at": "2026-09-29T10:15:00+07:00",
    "paid_at": "2026-09-28T10:31:04+07:00",
    "expired_at": null,
    "cancelled_at": null,
    "created_at": "2026-09-28T10:15:00+07:00",
    "payment_url": "https://payment-reader.ragh.co.id/pay/pay_01j8zq5v3m7c2k9x4h6t1r0bna",
    "mutation": {
      "id": "mut_01j8zqb7r2s3t4v5w6x7y8z9a0",
      "counterparty_name": "BUDI SANTOSO",
      "transaction_at": "2026-09-28T10:31:00+07:00",
      "received_at": "2026-09-28T10:31:04+07:00"
    }
  }
}

Contoh account.terminated:

{
  "event": "account.terminated",
  "event_id": "evt_01j8zz9x8w7v6t5s4r3q2p1n0m",
  "api_version": "2026-09-28",
  "created_at": "2026-09-30T09:00:00+07:00",
  "test": false,
  "data": { "merchant_id": "mer_01j8zk3m4n5p6q7r8s9t0v1w2x", "reason": "Pelanggaran syarat layanan", "at": "2026-09-30T09:00:00+07:00" }
}

Setelah account.terminated, semua kunci API dicabut dan tagihan pending dibatalkan. Hentikan pembuatan tagihan dan jangan arahkan pembeli ke halaman bayar lagi.

Verifikasi tanda tangan#

Tanda tangan membuktikan request benar-benar dari Reader dan isinya tidak diubah.

X-Reader-Signature = "sha256=" + hex( HMAC_SHA256( webhook_secret, timestamp + "." + body ) )

Langkah verifikasi:

1. Ambil body mentah persis seperti diterima, sebelum di-parse. Jangan mem-parse lalu meng-encode ulang JSON: urutan field, spasi, dan escape bisa berubah, sehingga tanda tangan tidak cocok.
2. Ambil header X-Reader-Timestamp. Tolak bila bukan angka, atau selisihnya dengan jam server Anda lebih dari 300 detik. Ini mencegah request lama diputar ulang.
3. Hitung HMAC-SHA256 dengan kunci = webhook secret (seluruh string whsec_…, apa adanya) dan pesan = timestamp + "." + body.
4. Bentuk "sha256=" + hex huruf kecil, lalu bandingkan dengan header X-Reader-Signature memakai perbandingan waktu-konstan (hash_equals, crypto.timingSafeEqual, hmac.Equal, hmac.compare_digest).
5. Bila tidak cocok, balas 401. Reader akan mengirim ulang sesuai jadwal.

Pastikan jam server Anda tersinkron (NTP). Jam yang meleset lebih dari 5 menit membuat semua webhook ditolak.

Kontrak ack#

Setiap webhook wajib dibalas dalam 10 detik dengan HTTP 2xx dan body JSON:

{ "event_id": "evt_01j8zqa2b3c4d5e6f7g8h9j0km", "status": "accepted" }

• event_id harus sama persis dengan event_id di body webhook.
• status salah satu dari empat nilai di bawah.
• reason (string) opsional, dipakai bersama rejected.

Contoh menolak:

{ "event_id": "evt_01j8zqa2b3c4d5e6f7g8h9j0km", "status": "rejected", "reason": "order ORDER-123 tidak ditemukan" }

Pakai rejected hanya bila event memang tidak bisa diproses, dan perlu dilihat manusia. Untuk kejadian yang bisa Anda tangani sendiri (misalnya pesanan sudah dipenuhi), balas accepted atau duplicate.

Kenapa ack wajib#

Banyak server membalas 200 untuk URL yang salah: halaman beranda, halaman login, atau rute cadangan aplikasi SPA. Tanpa ack, webhook yang tidak pernah diproses akan tampak "sukses". Dengan ack, Reader tahu pasti bahwa kode webhook Anda yang membalas.

Anda bisa mematikan kewajiban ack per aplikasi di dashboard. Setelah itu, balasan 2xx apa pun dianggap berhasil, termasuk dari URL yang salah.

Pemetaan respons#

Setiap percobaan kirim dicatat dengan kode di dashboard. Kode yang sama muncul di last_error_code dan last_delivery.error_code pada GET /api/v1/webhook-events.

Ack dianggap valid bila: status HTTP 2xx, body berupa objek JSON, event_id sama persis, dan status salah satu dari accepted, duplicate, rejected, retry. Header Content-Type balasan tidak diperiksa.

Yang disimpan untuk setiap percobaan: waktu, kode HTTP, 2 KB pertama body balasan, header Content-Type, Retry-After, dan Location, durasi, kode error, dan pemicunya. Detail percobaan disimpan 90 hari.

Jadwal kirim ulang#

percobaan 1 : seketika
percobaan 2 : 1 menit setelah percobaan 1 gagal
percobaan 3 : 5 menit setelah percobaan 2 gagal
berikutnya  : tiap 15 menit
berhenti    : 72 jam sejak percobaan pertama → status failed

• Bila balasan membawa header Retry-After dalam detik, percobaan berikutnya tidak lebih cepat dari nilai itu, dengan batas 1 jam.
• Jadwal berjalan per menit, jadi waktunya bisa bergeser hingga sekitar satu menit.
• Event failed tidak dikirim otomatis lagi, tetapi masih bisa dikirim ulang manual kapan saja.

Selama gagal terus, pemilik dan admin akun dikabari lewat email (dan WhatsApp, bila nomor HP terisi di profil) setelah 1 jam, lalu setiap 24 jam selama belum pulih.

Pemutus sirkuit#

Bila endpoint Anda gagal 3 kali berturut-turut, Reader membuka "sirkuit" untuk endpoint itu, supaya server Anda tidak dibanjiri request yang pasti gagal:

1. Event lain untuk endpoint itu tidak dicoba satu per satu.
2. Setiap 15 menit, hanya satu event tertua yang dikirim sebagai penguji.
3. Begitu penguji berhasil, sirkuit ditutup, lalu semua event yang tertunda dikirim berurutan sesuai waktu dibuat.

Balasan ack apa pun, termasuk rejected dan retry, membuktikan endpoint bisa dihubungi, sehingga tidak dihitung sebagai kegagalan. Kirim ulang manual yang berhasil juga langsung menutup sirkuit.

Batas 72 jam tetap dihitung per event selama sirkuit terbuka.

Kirim ulang manual#

Setelah memperbaiki server, Anda tidak perlu menunggu jadwal otomatis.

Kenapa tombol massal dibatasi 30 menit: ratusan event lama yang dikirim sekaligus bisa menjatuhkan server Anda yang baru pulih, dan lebih mungkin diproses dua kali oleh kode yang belum idempoten. Event yang lebih tua tetap diurus jadwal otomatis, atau bisa dikirim ulang satu per satu.

Jeda pengiriman#

Saat maintenance, Anda bisa menjeda pengiriman dari dashboard, menu Webhook.

• Event tetap dibuat dan disimpan, lalu dikirim setelah jeda dibuka.
• Batas 72 jam tetap dihitung selama jeda.
• Kirim ulang manual per event tetap bisa dipakai selama jeda.

Endpoint dinonaktifkan (410)#

Membalas 410 Gone berarti "endpoint ini sudah tidak ada". Reader langsung:

• menonaktifkan endpoint aplikasi itu dan menghentikan semua pengiriman otomatis;
• mengabari Anda lewat email (dan WhatsApp, bila nomor HP terisi di profil).

Event yang belum terkirim tetap disimpan. Setelah endpoint siap, tekan Aktifkan lagi di dashboard. Event yang menunggu dikirim di jadwal berikutnya, selama belum lewat 72 jam sejak percobaan pertamanya. Jangan pernah membalas 410 untuk kesalahan sementara.

Rotasi webhook secret#

Merotasi secret dilakukan dari dashboard dan meminta OTP email. Secret baru langsung dipakai untuk semua percobaan kirim berikutnya, termasuk kirim ulang event lama.

Supaya tidak ada webhook yang ditolak saat pergantian:

1. Ubah kode Anda agar sementara menerima tanda tangan dari secret lama atau secret baru.
2. Rotasi secret di dashboard, lalu pasang secret baru di server.
3. Setelah beberapa menit, hapus secret lama dari kode.

Webhook yang sempat ditolak (SIGNATURE_REJECTED) akan dikirim ulang sesuai jadwal.

Urutan dan idempotensi#

• Urutan event tidak dijamin. Event yang dikirim ulang bisa tiba setelah event yang lebih baru. Contoh: payment.expired yang tertunda bisa tiba setelah payment.paid. Jangan pernah menurunkan status pesanan yang sudah lunas karena event yang datang belakangan. Bila ragu, baca status terbaru dengan GET /api/v1/payments/{id}.
• Satu event bisa tiba lebih dari sekali, misalnya bila ack Anda tidak sampai karena timeout. Simpan event_id yang sudah diproses dengan indeks unik, dan balas duplicate untuk event yang berulang.
• Idealnya, catat event_id dan perubahan pesanan dalam satu transaksi database, supaya keduanya tidak pernah setengah jadi.
• Satu tagihan bisa menghasilkan beberapa event berbeda (misalnya payment.paid lalu payment.verified, atau payment.paid lalu payment.duplicate). Masing-masing punya event_id sendiri.

Menangani telat dan dobel#

Uji endpoint#

Tombol Uji endpoint di halaman aplikasi mengirim event ping:

{
  "event": "ping",
  "event_id": "evt_01j8zv4w5x6y7z8a9b0c1d2e3f",
  "api_version": "2026-09-28",
  "created_at": "2026-09-28T09:00:00+07:00",
  "test": false,
  "data": { "message": "Uji webhook dari RAGH Reader", "app_id": "app_01j8zk7p8q9r0s1t2v3w4x5y6z" }
}

Balas dengan ack seperti biasa. Hasilnya langsung tampil di dashboard, lengkap dengan kode respons dan body balasan Anda.

Untuk menguji alur lengkap tagihan, pakai kunci uji dan POST /api/v1/test/simulate.

Daftar IP pengirim#

Daftar IP pengirim webhook belum dipublikasikan. Halaman ini akan memuatnya setelah tersedia. Sementara itu, jangan membatasi endpoint hanya dengan allowlist IP. Verifikasi tanda tangan adalah perlindungan utamanya.

Checklist sebelum go-live#

• Callback URL memakai HTTPS dengan sertifikat valid, dan tidak me-redirect.
• Tanda tangan diverifikasi dari body mentah, dengan perbandingan waktu-konstan.
• Timestamp ditolak bila selisihnya lebih dari 5 menit, dan jam server tersinkron NTP.
• Balasan berupa JSON ack dengan event_id yang sama, dalam 10 detik.
• Pekerjaan berat (email, pembuatan akses, sinkronisasi) dipindah ke antrean.
• event_id disimpan dengan indeks unik. Event berulang dibalas duplicate.
• Event dengan test: true tidak memproses pesanan sungguhan.
• payment.paid dengan late: true tetap memenuhi pesanan.
• payment.duplicate tidak memenuhi pesanan dua kali, dan dicatat untuk refund.
• payment.expired tidak dianggap final, dan tidak membatalkan pesanan yang sudah dipenuhi.
• Status pesanan lunas tidak pernah diturunkan oleh event yang datang belakangan.
• Jenis event yang tidak dikenal dibalas accepted.
• rejected hanya dipakai untuk kasus yang perlu dilihat manusia, dengan reason yang jelas.
• Tombol Uji endpoint di dashboard menghasilkan DELIVERED.
• Bila memakai payout: payout.sent, payout.duplicate, dan payout.reversed ditangani, termasuk recipient_check: "mismatch".
• account.terminated menghentikan pembuatan tagihan baru.