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

Panduan ini untuk endpoint terdaftar melalui webhook.add: URL HTTPS publik dan event yang didukung, seperti order.processing, order.in_progress, order.completed, order.partial, order.refunded, dan order.refill_completed. Simpan secret; webhook.list tidak mengembalikannya. Periksa keadaan dan kegagalan melalui webhook.list, lalu hapus endpoint melalui webhook.remove.

Pengiriman API berisi array events, meski hanya satu event. Setiap item punya id, event, timestamp, dan data; deliveryId mengidentifikasi pengiriman. Contoh ringkas hanya ilustrasi. Tanggal lamanya tidak sesuai untuk menguji toleransi waktu.

{
  "events": [
    {
      "id": "EXAMPLE_EVENT_ID",
      "event": "order.completed",
      "timestamp": 1700000000,
      "data": { "order": 7001, "status_key": "completed" }
    }
  ],
  "timestamp": 1700000001,
  "deliveryId": "EXAMPLE_DELIVERY_ID"
}

Baca nama event dari body yang diverifikasi: batch API tidak memerlukan X-Webhook-Event. Webhook dari dashboard memakai format berbeda dengan satu event; jangan menganggap keduanya 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. Cocokkan X-Webhook-Delivery-Id dengan deliveryId pada body terverifikasi. Simpan pengiriman sebelum menjawab 2xx; jika belum bisa menerima dengan aman, biarkan pengirim mencoba lagi.
3. Proses setiap events[].id sekali. Pertahankan pendeteksian duplikasi setelah restart bersama pembaruan pesanan. Event sama bisa tiba melalui beberapa endpoint.
4. Lakukan pekerjaan lambat setelah penerimaan. Tanda tangan membuktikan keaslian, bukan urutan. Jika event terlambat bertentangan dengan keadaan baru, periksa status sebelum menggantinya.

Panduan verifikasi tanda tangan

Ketika penerima tidak tersedia

Timeout atau respons bukan 2xx dihitung gagal. NotPanel mencoba kembali dengan jeda meningkat dan menjeda endpoint API setelah 10 kegagalan berturut-turut; keberhasilan 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 yang dijeda, pastikan pendaftaran aktif. Jangan menganggap seluruh pengiriman lama yang gagal otomatis dikirim ulang.

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.
• Satu event dalam dua batch dan restart tidak boleh menduplikasi pembaruan.
• 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. Cocokkan X-Webhook-Delivery-Id dengan deliveryId di body terverifikasi, lalu proses array events.

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.