Untuk mengintegrasikan sistem aplikasi atau toko online Anda secara otomatis dengan layanan Biteship, Anda dapat menggunakan fitur Webhook.
Fitur ini memungkinkan sistem Anda menerima notifikasi secara real-time mengenai perubahan status pengiriman tanpa harus melakukan pengecekan manual secara terus-menerus ke API Biteship.
Artikel ini akan membantu Anda memahami:
- Apa itu Webhook Biteship
- Manfaat menggunakan Webhook untuk operasional
- Event yang didukung oleh Webhook Biteship
- Langkah-langkah melakukan konfigurasi
- Keamanan dan verifikasi Webhook
- Tips penanganan data (Best Practices)
1. Apa Itu Webhook Biteship?
Webhook adalah sebuah mekanisme yang digunakan oleh Biteship untuk mengirimkan data atau informasi secara otomatis ke server/aplikasi Anda segera setelah sebuah peristiwa (event) terjadi.
Jika API biasa mengharuskan Anda "bertanya" (pull data), Webhook bekerja dengan cara "memberi tahu" (push data). Contohnya, saat status paket berubah, Biteship akan langsung mengirimkan data status tersebut ke URL yang Anda tentukan.
2. Manfaat Menggunakan Webhook
Dengan mengaktifkan Webhook, bisnis Anda akan mendapatkan efisiensi sebagai berikut:
- Update Real-Time: Status pesanan di aplikasi Anda berubah otomatis saat kurir memperbarui status di lapangan.
- Efisiensi Resource: Anda tidak perlu melakukan polling API berulang kali yang dapat membebani server.
- Otomatisasi Lanjutan: Anda bisa memicu aksi otomatis lainnya, seperti mengirimkan notifikasi email atau WhatsApp ke pembeli saat status paket berubah.
- Sinkronisasi Data: Memastikan data antara dashboard Biteship dan database internal Anda selalu selaras.
3. Event yang Didukung oleh Webhook Biteship
Biteship menyediakan notifikasi untuk berbagai peristiwa penting dalam siklus pengiriman, di antaranya:
- order.status: Dikirimkan setiap kali ada perubahan status pengiriman, beserta informasi kurir, nomor resi, dan detail driver (untuk layanan instant).
- order.waybill_id: Dikirimkan saat nomor resi resmi dari kurir telah diterbitkan.
- order.price: Dikirimkan saat terdapat pembaruan pada harga pesanan.
4. Cara Melakukan Konfigurasi Webhook
Langkah 1: Siapkan URL Endpoint
Siapkan sebuah URL pada server Anda yang siap menerima data dalam format JSON via metode POST. Pastikan URL dapat diakses secara publik dan menggunakan protokol HTTPS.
Langkah 2: Buka Halaman Webhook di Dashboard Biteship
Masuk ke akun Biteship Anda, lalu navigasikan ke menu Integrasi. Pilih tab Untuk Developer, kemudian klik kartu Webhook.
Langkah 3: Tambahkan Webhook Baru
Klik tombol Tambah Webhook. Pada modal yang muncul, isi kolom-kolom berikut:
- Nama Webhook — identifikasi webhook Anda (wajib diisi)
- Deskripsi Webhook — keterangan tambahan (opsional)
- URL Webhook — alamat endpoint server Anda (wajib diisi)
- Event — pilih satu atau lebih event yang ingin dipantau (order.status, order.waybill_id, order.price)
Pada bagian Headers (Optional), Anda dapat mengisi Headers Signature Key dan Headers Signature Secret untuk keamanan tambahan. Klik Buat untuk menyimpan.
Langkah 4: Verifikasi via Events Log
Setelah webhook aktif, pantau pengiriman notifikasi melalui tab Events Log di halaman Webhook. Di sini Anda dapat melihat histori pengiriman beserta status respons, request payload, dan response payload. Jika ada pengiriman yang gagal, gunakan tombol Resend untuk mengirim ulang secara manual.
5. Keamanan Webhook
Untuk memastikan data yang masuk ke server Anda benar-benar berasal dari Biteship, kami menyarankan:
- Headers Signature Key & Secret: Saat membuat Webhook, isi kolom Headers Signature Key dan Headers Signature Secret. Nilai ini akan dikirimkan sebagai header HTTP pada setiap request ke server Anda, sehingga Anda dapat memvalidasi bahwa request berasal dari Biteship.
- HTTPS: Pastikan endpoint URL Anda menggunakan protokol aman (HTTPS). URL yang tidak menggunakan HTTPS berisiko terhadap kebocoran data.
6. Tips Penanganan (Best Practices)
- Respon Cepat: Pastikan server Anda segera memberikan respons HTTP 200 OK setelah menerima data, sebelum melakukan proses logis yang berat.
- Antrean (Queue): Gunakan sistem antrean jika Anda perlu melakukan pemrosesan data yang lama, agar koneksi tidak timeout.
- Idempotency: Pastikan sistem Anda dapat menangani jika sewaktu-waktu Webhook mengirimkan data yang sama lebih dari satu kali.
- Pisahkan Environment: Buat Webhook terpisah untuk lingkungan pengembangan (test) dan produksi (live) agar data tidak tercampur.
7. FAQ Tentang Webhook
Bagaimana jika pengiriman Webhook gagal?
Jika pengiriman gagal (server tidak merespons atau mengembalikan error), Anda dapat melihat detail kegagalan di tab Events Log dan mengirim ulang secara manual menggunakan tombol Resend.
Apakah satu akun bisa memiliki lebih dari satu Webhook?
Ya, Anda dapat membuat beberapa Webhook sesuai kebutuhan, misalnya untuk memisahkan lingkungan test dan live. Setiap Webhook dapat dikonfigurasi dengan URL dan kombinasi event yang berbeda.
Event apa saja yang bisa dipantau melalui Webhook?
Untuk kebutuhan seller, event yang tersedia adalah order.status (perubahan status pengiriman), order.waybill_id (penerbitan nomor resi), dan order.price (pembaruan harga pesanan).
8. Kesimpulan
Webhook adalah solusi terbaik bagi bisnis yang ingin memberikan pengalaman pelanggan yang responsif melalui pembaruan status pengiriman otomatis. Dengan konfigurasi yang tepat, sistem Anda akan selalu tersinkronisasi dengan data terbaru dari Biteship secara real-time.
Jika Anda membutuhkan bantuan teknis mengenai integrasi Webhook, silakan merujuk pada Dokumentasi API Biteship atau hubungi tim support kami melalui support@biteship.com.