Webhook

Webhook mengirim kabar ke servermu setiap kali status pengiriman berubah atau isi saldo masuk. Dengan webhook, sistemmu tidak perlu memanggil GET /v1/shipments/{id} berulang kali untuk tahu kapan resi terbit atau paket terkirim.

OngkirHub mengirim POST berisi JSON ke URL HTTPS milikmu. Setiap kiriman ditandatangani dengan header OngkirHub-Signature, dan kiriman yang gagal dicoba ulang otomatis. Ringkasannya ada di bagian Webhook video Cara integrasi Developer API.

Memasang endpoint

Hanya pemilik dan admin workspace yang bisa membuka menu Developer.

1. Siapkan URL di servermu yang menerima POST, misalnya https://tokoku.id/webhooks/ongkirhub. URL harus HTTPS, bisa diakses dari internet, dan tidak memuat nama pengguna atau password.
2. Buka menu Developer di OngkirHub App, lalu tab Webhook.
3. Tekan Tambah endpoint, isi URL, dan bila perlu Keterangan.
4. Pilih Event yang ingin diterima. Semua event dicentang secara bawaan.
5. Tekan Tambah endpoint. Dialog Secret endpoint menampilkan secret berawalan whsec_. Salin dan simpan di variabel lingkungan servermu.
6. Pasang verifikasi tanda tangan seperti di Verifikasi tanda tangan.
7. Tekan Kirim tes di baris endpoint, lalu periksa hasilnya di tab Log webhook.

Satu workspace bisa punya sampai 10 endpoint. Dari menu titik tiga di setiap endpoint, kamu bisa Ubah, Tampilkan secret, Ganti secret, Nonaktifkan atau Aktifkan lagi, dan Hapus.

Daftar event

Event	Label di menu Developer	Dikirim saat
shipment.booked	Pesanan diterima kurir	Status berubah menjadi booked: kurir menerima pesanan dan saldo yang ditahan terpakai.
shipment.awb_ready	Resi terbit	Status berubah menjadi awb_ready: nomor resi ada di data.shipment.awb dan label siap dicetak.
shipment.status_updated	Status perjalanan berubah	Status berubah menjadi picked_up, in_transit, out_for_delivery, problem, returned, atau cancel_requested.
shipment.delivered	Paket terkirim	Status berubah menjadi delivered.
shipment.failed	Pesanan gagal dibuat	Kurir menolak pesanan. Saldo yang ditahan sudah dikembalikan, alasannya di data.shipment.error.
shipment.cancelled	Pembatalan disetujui	Pembatalan disetujui dan saldo dikembalikan.
topup.paid	Isi saldo dibayar	Admin OngkirHub mengaktifkan isi saldo dan saldo bertambah.
webhook.test	Tidak perlu dipilih	Hanya dari tombol Kirim tes.

Event pengiriman dikirim untuk semua pengiriman di workspace, baik yang dibuat lewat API maupun dari aplikasi. Field data.shipment.source berisi api atau app. Isi lengkap setiap event ada di Daftar event.

Kalau pengajuan pembatalan ditolak, status kembali ke status sebelumnya dan event untuk status itu dikirim lagi dengan previousStatus bernilai cancel_requested.

Format kiriman

Setiap kiriman adalah POST dengan Content-Type: application/json dan header berikut:

Header	Isi
OngkirHub-Signature	t=<detik unix>,v1=<hex>. Dipakai untuk verifikasi, lihat Verifikasi tanda tangan.
OngkirHub-Event	Jenis event, misalnya shipment.awb_ready.
OngkirHub-Delivery	ID kiriman. Sama untuk setiap percobaan ulang kiriman yang sama.
User-Agent	OngkirHub-Webhooks/1.0

Body-nya punya lima field di tingkat atas:

{
  "id": "evt_3f2a1b0c9d8e7f6a5b4c3d2e",
  "type": "shipment.awb_ready",
  "createdAt": "2026-10-11T03:02:10.000Z",
  "livemode": true,
  "data": {
    "shipment": { "id": "OH0HZ3K7Q2M4XB", "status": "awb_ready", "awb": "CGK0123456789012" },
    "previousStatus": "booked"
  }
}

Contoh di atas dipangkas. data.shipment berisi objek pengiriman lengkap, sama dengan respons GET /v1/shipments/{id}.

Menjawab kiriman

• Jawab dengan status 2xx dalam 10 detik. Isi body jawabanmu tidak dibaca, kecuali 500 karakter pertama yang tampil di Log webhook untuk membantu debugging.
• Status lain, timeout, error koneksi, dan redirect dianggap gagal. Redirect tidak diikuti, jadi pakai URL akhir.
• Verifikasi tanda tangan dulu, lalu simpan event dan jawab 2xx. Kerjakan proses yang berat, misalnya memperbarui pesanan atau mengirim email, di antrean milikmu setelah menjawab.

Percobaan ulang

Kiriman yang gagal dicoba ulang setelah 1 menit, 5 menit, 30 menit, 2 jam, 6 jam, dan 24 jam. Jadi satu kiriman dicoba paling banyak tujuh kali. Antrean diproses setiap menit, sehingga waktu nyatanya bisa sedikit bergeser.

Endpoint dinonaktifkan otomatis setelah 20 kiriman gagal berturut-turut. Hitungannya kembali ke nol setiap kali ada kiriman yang berhasil. Saat endpoint dinonaktifkan, kamu menerima notifikasi di aplikasi. Perbaiki servermu, pilih Aktifkan lagi di menu endpoint, lalu kirim ulang event yang terlewat dari Log webhook.

Duplikat dan urutan

Webhook dikirim setidaknya sekali. Satu event bisa tiba lebih dari sekali, misalnya saat jawabanmu terlambat, dan event bisa tiba tidak berurutan.

• Simpan id setiap event yang sudah diproses, lalu abaikan event dengan id yang sama. id tidak berubah saat dicoba ulang atau dikirim ulang.
• Jawab 2xx juga untuk event duplikat supaya tidak dicoba ulang terus.
• Untuk urutan, bandingkan data.shipment.updatedAt dengan data yang sudah kamu simpan, dan abaikan event yang lebih lama. Bila ragu, ambil status terbaru dengan GET /v1/shipments/{id}.

Test dan live

Satu endpoint menerima event dari pengiriman test maupun live. Field livemode bernilai false untuk pengiriman yang dibuat dengan kunci test dan untuk event webhook.test. Simpan atau abaikan event uji sesuai kebutuhanmu, tetapi jangan sampai mengubah data produksi. Penjelasan mode test ada di Mode test.

Log webhook dan kirim ulang

Tab Log webhook di menu Developer menampilkan setiap kiriman 30 hari terakhir: waktu, event, endpoint, status (Menunggu, Mengirim, Terkirim, atau Gagal), jumlah percobaan, dan respons endpoint. Tekan Lihat untuk melihat body yang dikirim dan potongan respons servermu.

Untuk kiriman berstatus Terkirim atau Gagal, tekan Kirim ulang. Kiriman masuk antrean lagi dengan body yang sama, termasuk id event yang sama, dan dikirim dalam beberapa detik.

Praktik terbaik

• Verifikasi OngkirHub-Signature di setiap kiriman dan tolak yang tidak cocok.
• Tolak kiriman dengan t yang selisihnya lebih dari 5 menit dari jam servermu, dan pastikan jam server sinkron.
• Simpan secret di variabel lingkungan. Kalau secret bocor, pilih Ganti secret. Secret lama langsung tidak berlaku, jadi pasang secret baru di servermu segera.
• Pakai endpoint terpisah untuk lingkungan yang berbeda, misalnya produksi dan staging, lalu pilih hanya event yang kamu butuhkan.
• Proses event secara idempoten berdasarkan id, dan jangan bergantung pada urutan kedatangan.
• Pantau Log webhook setelah deploy, terutama kiriman berstatus Gagal.