Webhook

• Konfigurasi
• Verifikasi
• Header Event Name
• Payload
• Respons

Webhook memungkinkan Anda menerima pembaruan real-time tentang transaksi Anda. Ketika status transaksi diperbarui, kami akan mengirimkan permintaan POST ke URL yang telah Anda konfigurasikan.

Konfigurasi

Anda dapat mengkonfigurasi URL webhook Anda di halaman "Pengaturan Webhook" pada dashboard merchant Anda. Anda juga akan diberikan kunci rahasia yang harus Anda gunakan untuk memverifikasi keaslian webhook.

Untuk mengirimkan URL webhook dan kunci rahasia Anda:

1. Masuk ke dashboard merchant Anda.
2. Navigasi ke bagian "Pengaturan Webhook" (biasanya di bawah menu Pengaturan atau Integrasi).
3. Masukkan URL endpoint webhook Anda di kolom yang tersedia.
4. Masukkan kunci rahasia yang telah Anda buat atau yang diberikan kepada Anda.
5. Simpan perubahan Anda.

Verifikasi

Untuk memastikan bahwa permintaan webhook berasal dari kami, kami akan menyertakan tanda tangan (signature) di header X-Ongkirmurah-Signature. Tanda tangan tersebut adalah hash HMAC-SHA256 dari timestamp dan payload permintaan, menggunakan kunci rahasia Anda.

Berikut adalah contoh cara memverifikasi tanda tangan di PHP:

$secret = 'kunci-rahasia-webhook-anda';
$payload = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_ONGKIRMURAH_TIMESTAMP'];
$signature = $_SERVER['HTTP_X_ONGKIRMURAH_SIGNATURE'];

$expectedSignature = hash_hmac('sha256', $timestamp . '.' . $payload, $secret);

if ($signature !== $expectedSignature) {
    // Tanda tangan tidak valid
    http_response_code(401);
    exit();
}

Header Event Name

Untuk mengidentifikasi jenis event webhook, kami menyertakan header X-Ongkirmurah-Event dengan nama event yang relevan. Berikut adalah daftar event yang mungkin Anda terima:

Payload

Payload akan berupa objek JSON dari attribut data dengan struktur yang sama seperti respons dari API Pelacakan.

{
    "awb": "JNE1234567890",
    "courier_name": "JNE Express",
    "history": [
        {
            "datetime": "2025-06-28 10:00:00",
            "message": "Paket diterima di kantor cabang pengirim",
            "note": "-"
        }
    ],
    "item_height": 5,
    "item_length": 20,
    "item_name": "Baju Kaos",
    "item_type": "Pakaian",
    "item_value": 100000,
    "item_weight": 500,
    "item_width": 15,
    "receiver_address": "Jl. Penerima No. 45, RT 003 RW 004",
    "receiver_city": "Kota Tujuan",
    "receiver_district": "Kecamatan Tujuan",
    "receiver_name": "Siti Aminah",
    "receiver_phone": "089876543210",
    "receiver_province": "Provinsi Tujuan",
    "receiver_subdistrict": "Kelurahan Tujuan",
    "receiver_zip_code": "54321",
    "ref_id": "JNE123456789",
    "sender_address": "Jl. Contoh No. 123, RT 001 RW 002",
    "sender_city": "Kota Contoh",
    "sender_district": "Kecamatan Contoh",
    "sender_name": "Budi Santoso",
    "sender_phone": "081234567890",
    "sender_province": "Provinsi Contoh",
    "sender_subdistrict": "Kelurahan Contoh",
    "sender_zip_code": "12345",
    "service_code": "REG",
    "service_name": "Reguler",
    "fee": 10000,
    "fee_tax": 1000,
    "insurance": 5000,
    "insurance_tax": 500,
    "total_fee": 16500,
    "supplier_calculation_adjustment": {
        "weight": 1200,
        "length": 25,
        "width": 20,
        "height": 10,
        "fee": 12000,
        "insurance": 6000,
        "return_cost": 0
    },
    "shipment_status": 0,
    "status": 1
}

Respons

Endpoint Anda harus mengembalikan kode status HTTP 2xx untuk mengakui penerimaan webhook. Jika kami tidak menerima kode status 2xx, kami akan menganggap pengiriman webhook gagal dan akan mencoba kembali beberapa kali dengan strategi backoff eksponensial.