Webhook atau polling? Pelacakan pesanan yang bisa pulih

Gunakan webhook untuk perubahan rutin dan pertahankan pemeriksaan status agar catatan Anda sesuai dengan panel. Jika belum memiliki penerima publik yang andal, mulailah dengan polling batch.

Pesanan dapat selesai saat aplikasi dimulai ulang. Event bisa tiba dua kali jika konfirmasi hilang. Pelacakan perlu menangani keduanya tanpa menampilkan informasi lama atau menerapkan pembaruan dua kali.

Tugas yang jelas untuk setiap metode

Polling: meminta keadaan saat ini

action=status mengembalikan keadaan saat pemeriksaan. Gabungkan hingga 100 ID per permintaan. Interval lebih pendek menghasilkan lebih banyak permintaan, termasuk saat tidak ada perubahan.

Webhook: menerima perubahan terpilih

NotPanel mengirim event ke URL HTTPS Anda. Pengiriman tidak memakai kuota permintaan status klien, tetapi penerima tetap membutuhkan kapasitas dan pemantauan.

Rekonsiliasi: memulihkan informasi yang hilang

Setelah gangguan atau ketika catatan tampak lama, periksa pesanan terkait. Event bisa terlewat, percobaan terbatas, dan waktu kedatangan tidak dijamin.

Yang dikirim oleh API NotPanel

Tambahkan endpoint di halaman API dashboard Anda atau melalui webhook.add: URL HTTPS publik dan event yang Anda perlukan, seperti order.processing, order.in_progress, order.completed, order.partial, order.canceled, order.cancel_refused, refill.completed, dan refill.rejected; referensi webhook mencantumkan semuanya. Simpan secret dengan aman: secret hanya ditampilkan sekali dan webhook.list tidak pernah mengembalikannya. Periksa endpoint melalui webhook.list, kirim ping uji melalui webhook.test, dan hapus endpoint melalui webhook.remove.

Setiap pengiriman membawa satu event dalam amplop ringkas: id, type, schema_version, created_at, sequence, dan data. data.order berisi field yang sama dengan respons action=status. Contoh ringkas di bawah menunjukkan bentuknya, bukan pesanan nyata.

{
  "id": "EXAMPLE_EVENT_ID",
  "type": "order.completed",
  "schema_version": 1,
  "created_at": "2026-10-10T12:30:00Z",
  "sequence": 1042,
  "data": {
    "order": {
      "order": 7001,
      "status": "Completed",
      "status_key": "completed",
      "remains": "0"
    }
  }
}

Baca jenis event dari body yang diverifikasi. X-Webhook-Event juga dikirim, tetapi tidak ditandatangani. Endpoint dari dashboard dan dari API menerima amplop yang sama.

Terima event dengan aman

1. Simpan body asli. Verifikasi X-Webhook-Signature memakai secret dan X-Webhook-Timestamp, lalu terapkan toleransi waktu Anda. Menyusun ulang body bisa mengubah byte bertanda tangan.
2. Catat X-Webhook-Delivery-Id untuk melacak percobaan; nilainya sama pada setiap percobaan ulang pengiriman itu. Simpan event terverifikasi sebelum menjawab 2xx; jika belum bisa menerima dengan aman, biarkan pengirim mencoba lagi.
3. Proses setiap id event sekali. Pertahankan pendeteksian duplikasi setelah restart bersama pembaruan pesanan. Id event yang sama tiba di setiap endpoint yang berlangganan event itu.
4. Lakukan pekerjaan lambat setelah penerimaan. Tanda tangan membuktikan keaslian, bukan urutan. Gunakan sequence untuk mengurutkan event, dan jika event terlambat bertentangan dengan keadaan baru, periksa status sebelum menggantinya.

Panduan verifikasi tanda tangan

Ketika penerima tidak tersedia

Timeout (10 detik) atau respons bukan 2xx adalah percobaan gagal. NotPanel mencoba setiap pengiriman hingga 8 kali dalam 24 jam: langsung, lalu 1 menit, 5 menit, 30 menit, 2 jam, 6 jam, 12 jam, dan 24 jam setelah event. Endpoint dijeda setelah 50 kegagalan berturut-turut atau 3 hari tanpa keberhasilan, dan pemilik akun diberi tahu. Pengiriman yang berhasil menghapus hitungannya. Pantau webhook.list: tidak ada kiriman bukan bukti tidak ada perubahan.

Periksa berkala pesanan belum selesai atau lama dalam batch hingga 100 ID, sesuai header dan batas akun. Setelah memperbaiki penerima, lanjutkan endpoint di bagian webhook pada halaman API dashboard Anda; hitungan kegagalannya akan dihapus. Atau hapus dengan webhook.remove, tambahkan lagi URL HTTPS yang diperbaiki beserta event pilihan melalui webhook.add, simpan secret baru dengan aman, dan perbarui verifikasi penerima. API publik tidak menyediakan aksi untuk melanjutkan endpoint. Pengiriman yang mengantre saat endpoint dijeda tidak dikirim ulang, jadi cocokkan status yang terlewat melalui status.

Uji lebih dari satu pengiriman berhasil

Gunakan pesan buatan dan secret pengujian sendiri; pesanan pelanggan tidak diperlukan.

• Pengiriman yang sama dua kali harus memberi satu pembaruan.
• Event yang sama dikirim dua kali dengan restart di antaranya tetap harus dikenali.
• Satu byte berubah atau waktu lama harus gagal sesuai kebijakan Anda.
• Setelah gangguan dan event terlambat, status harus memulihkan tampilan terkini.

Pemilihan event, verifikasi secret, dan konfirmasi cepat juga dijelaskan dalam panduan webhook GitHub. Header, format, dan batas percobaan di sini mengikuti kontrak NotPanel.

Pertanyaan umum

Bolehkah hanya memakai polling?

Ya. Gabungkan pemeriksaan dan sesuaikan interval dengan volume serta batas akun. Webhook tidak wajib untuk membuat atau melacak pesanan.

Apakah webhook selalu langsung tiba tepat sekali?

Tidak. Pengiriman bisa terlambat atau berulang. Verifikasi setiap pengiriman, terapkan setiap event sekali, dan pertahankan pemeriksaan status untuk pemulihan.

Header apa yang perlu diperiksa?

Periksa X-Webhook-Signature dan X-Webhook-Timestamp, lalu baca id, type, dan data dari body terverifikasi. Gunakan X-Webhook-Delivery-Id hanya untuk melacak percobaan.

Apakah webhook melindungi add yang belum pasti?

Itu dua masalah berbeda. Ulangi add dengan request_id asli dan parameter sama, lalu simpan ID pesanan yang ditemukan.

Referensi: kontrak webhook · status pesanan · pemulihan timeout.