Daftar event webhook

Semua event memakai amplop yang sama. Isi data berbeda per jenis event.

Field	Isi
id	ID event, diawali evt_. Sama untuk setiap percobaan ulang. Pakai untuk membuang duplikat.
type	Jenis event, sama dengan header OngkirHub-Event.
createdAt	Waktu event dibuat, ISO 8601 UTC.
livemode	false untuk pengiriman dari kunci test dan untuk webhook.test.
data	Isi event, lihat di bawah.

Event pengiriman

Enam event berikut membawa data.shipment dan data.previousStatus.

Event	Status baru (data.shipment.status)
shipment.booked	booked
shipment.awb_ready	awb_ready
shipment.status_updated	picked_up, in_transit, out_for_delivery, problem, returned, atau cancel_requested
shipment.delivered	delivered
shipment.failed	failed
shipment.cancelled	cancelled

• data.shipment adalah objek pengiriman lengkap, sama dengan respons GET /v1/shipments/{id}. Skemanya ada di referensi Pengiriman.
• data.previousStatus adalah status sebelum perubahan ini.

Field yang paling sering dipakai:

Field	Isi
data.shipment.id	ID pengiriman OngkirHub, OH diikuti 12 karakter.
data.shipment.externalRef	Referensi milikmu dari POST /v1/shipments, misalnya nomor pesanan toko. null bila tidak diisi.
data.shipment.status, statusLabel	Status OngkirHub dan labelnya dalam Bahasa Indonesia.
data.shipment.awb	Nomor resi. null sampai resi terbit.
data.shipment.courier, service	Kurir dan layanan, termasuk estimasi waktu sampai.
data.shipment.pricing	courierPrice, insurancePrice, serviceFee, dan total dalam rupiah.
data.shipment.tracking	Data pelacakan terakhir dari kurir, riwayat terbaru dulu.
data.shipment.error	Alasan gagal untuk shipment.failed, berisi code dan message.
data.shipment.source	api atau app.
data.shipment.updatedAt	Waktu perubahan terakhir. Pakai untuk menentukan urutan.

Contoh shipment.awb_ready

{
  "id": "evt_3f2a1b0c9d8e7f6a5b4c3d2e",
  "type": "shipment.awb_ready",
  "createdAt": "2026-10-11T03:02:10.000Z",
  "livemode": true,
  "data": {
    "shipment": {
      "id": "OH0HZ3K7Q2M4XB",
      "livemode": true,
      "status": "awb_ready",
      "statusLabel": "Resi terbit",
      "stage": "manifested",
      "courier": { "code": "jne", "name": "JNE" },
      "service": { "rateCode": "REG23", "name": "Reguler", "etd": { "min": 1, "max": 2, "unit": "DAY" } },
      "awb": "CGK0123456789012",
      "shipper": {
        "name": "Toko Contoh Jaya",
        "phone": "6281200000001",
        "email": "gudang@contoh.test",
        "address": "Jl. Contoh Raya No. 1, RT 01/RW 02, Setiabudi",
        "location": { "province": "DKI Jakarta", "city": "Jakarta Selatan", "district": "Setia Budi", "subdistrict": "Setiabudi", "zipcode": "12910" },
        "latlng": null
      },
      "receiver": {
        "name": "Dimas Pratama",
        "phone": "6281300000102",
        "email": null,
        "address": "Jl. Penerima No. 2, dekat masjid, Lebak Gede",
        "location": { "province": "Jawa Barat", "city": "Bandung", "district": "Coblong", "subdistrict": "Lebak Gede", "zipcode": "40132" },
        "latlng": null
      },
      "items": [
        {
          "name": "Kaos katun",
          "sku": "KAOS-HITAM-L",
          "qty": 2,
          "weightKg": 0.5,
          "value": 85000,
          "dimensions": { "lengthCm": 25, "widthCm": 20, "heightCm": 5 },
          "itemType": "REGULAR"
        }
      ],
      "parcel": { "weightKg": 1, "chargeableWeightKg": 1, "declaredValue": 170000 },
      "insurance": { "insured": false, "price": 0 },
      "pricing": { "courierPrice": 12000, "insurancePrice": 0, "serviceFee": 0, "total": 12000 },
      "pickup": { "type": "DROP", "time": null },
      "tracking": { "lastCheckedAt": null, "origin": null, "destination": null, "courierStatus": null, "events": [] },
      "timeline": [
        { "status": "submitting", "label": "Sedang diproses", "at": "2026-10-11T03:01:00.000Z", "note": null },
        { "status": "booked", "label": "Menunggu resi", "at": "2026-10-11T03:01:04.000Z", "note": null },
        { "status": "awb_ready", "label": "Resi terbit", "at": "2026-10-11T03:02:10.000Z", "note": null }
      ],
      "error": null,
      "externalRef": "INV-2026-10-0412",
      "notes": null,
      "payment": null,
      "source": "api",
      "createdAt": "2026-10-11T03:01:00.000Z",
      "updatedAt": "2026-10-11T03:02:10.000Z",
      "bookedAt": "2026-10-11T03:01:04.000Z",
      "deliveredAt": null
    },
    "previousStatus": "booked"
  }
}

Contoh shipment.failed

Contoh ini dipangkas. Saldo yang ditahan sudah dikembalikan saat event ini dikirim.

{
  "id": "evt_7c6b5a4f3e2d1c0b9a8f7e6d",
  "type": "shipment.failed",
  "createdAt": "2026-10-11T03:01:06.000Z",
  "livemode": true,
  "data": {
    "shipment": {
      "id": "OH0HZ3K7Q2M4XB",
      "status": "failed",
      "statusLabel": "Gagal",
      "awb": null,
      "error": {
        "code": "courier_rejected",
        "message": "Kurir belum bisa memproses pesanan ini. Coba layanan kurir lain. Saldomu tidak terpotong."
      },
      "externalRef": "INV-2026-10-0412",
      "updatedAt": "2026-10-11T03:01:06.000Z"
    },
    "previousStatus": "submitting"
  }
}

Menangani event pengiriman

Event	Yang biasanya dilakukan
shipment.booked	Tandai pesanan sudah diterima kurir.
shipment.awb_ready	Simpan nomor resi, kirim ke pembeli, dan cetak label.
shipment.status_updated	Perbarui status pesanan. Untuk problem, beri tanda agar timmu memeriksa.
shipment.delivered	Tandai pesanan selesai.
shipment.failed	Buat ulang pengiriman dengan layanan lain setelah cek tarif lagi.
shipment.cancelled	Tandai pesanan dibatalkan. Saldo sudah dikembalikan.

topup.paid

Dikirim saat isi saldo terkonfirmasi dan saldo bertambah. Isi saldo dilakukan lewat transfer bank BCA, jadi event dikirim setelah admin OngkirHub mengaktifkan isi saldo, bukan saat pengguna menekan Saya sudah transfer. Event ini selalu livemode: true.

Field	Isi
data.topup.code	Kode isi saldo, diawali TU.
data.topup.amount	Nominal yang masuk ke saldo.
data.topup.fee	Kode unik transfer, Rp50 sampai Rp999. Kode unik ikut ditransfer tetapi tidak masuk ke saldo.
data.topup.total	Total yang ditransfer (amount ditambah fee).
data.topup.method	manual_transfer, untuk transfer bank.
data.topup.status, statusLabel	paid dan “Berhasil”.
data.topup.purpose	null untuk isi saldo biasa.
data.topup.payment	null, karena isi saldo lewat transfer bank tidak memakai halaman pembayaran.
data.topup.manual	Detail transfer bank. uniqueCode berisi kode unik yang sama dengan fee, dan submittedAt waktu pengguna menekan Saya sudah transfer. Nomor rekening tidak ikut dikirim: bankAccounts selalu kosong.
data.balance.available	Saldo tersedia setelah isi saldo masuk.

{
  "id": "evt_9a8b7c6d5e4f3a2b1c0d9e8f",
  "type": "topup.paid",
  "createdAt": "2026-10-10T04:20:02.000Z",
  "livemode": true,
  "data": {
    "topup": {
      "code": "TU0HZ2Y1X0W9VA",
      "amount": 500000,
      "fee": 417,
      "total": 500417,
      "method": "manual_transfer",
      "status": "paid",
      "statusLabel": "Berhasil",
      "expiresAt": "2026-10-11T01:55:00.000Z",
      "paidAt": "2026-10-10T04:20:00.000Z",
      "createdAt": "2026-10-10T01:55:00.000Z",
      "purpose": null,
      "payment": null,
      "manual": {
        "bankAccounts": [],
        "senderName": null,
        "senderBank": null,
        "uniqueCode": 417,
        "submittedAt": "2026-10-10T02:10:00.000Z",
        "rejectionReason": null,
        "proofUploadId": null
      }
    },
    "balance": { "available": 500000 }
  }
}

Nominal, kode unik, dan waktu di contoh hanya ilustrasi.

webhook.test

Dikirim hanya saat kamu menekan Kirim tes di tab Webhook menu Developer. Event ini tidak perlu dipilih saat mengatur endpoint dan selalu livemode: false.

{
  "id": "evt_0a1b2c3d4e5f6a7b8c9d0e1f",
  "type": "webhook.test",
  "createdAt": "2026-10-11T06:00:00.000Z",
  "livemode": false,
  "data": { "message": "Tes webhook dari OngkirHub" }
}

Jawab event ini dengan 2xx seperti event lain, lalu periksa hasilnya di tab Log webhook.