Webhooks

Webhooks

Webhook mengirim notifikasi POST ke URL Anda setiap kali status order berubah. Daftarkan endpoint di halaman Developers › Webhooks.

Daftar Event

Event	Keterangan
order.created	Order berhasil dibuat.
order.shipping	Paket dijemput dan dalam pengiriman.
order.delivered	Paket berhasil diterima.
order.problem	Terjadi masalah pengiriman (mis. gagal antar).
order.returned	Paket dikembalikan ke pengirim.
order.cancelled	Order dibatalkan.
order.failed	Order gagal diproses.

Payload

{
  "event": "order.delivered",
  "delivery_id": "whd_5c2a",
  "created_at": "2026-08-09T11:20:00+07:00",
  "data": {
    "id": "ord_3a9f",
    "resi": "TRK00012345",
    "no_order": "INV-20260808-0001",
    "status": "delivered",
    "courier_code": "ninja",
    "courier_service": "Standard",
    "charged_amount": 14000,
    "is_cod": false,
    "cod_amount": 0,
    "recipient_name": "Siti Rahma",
    "recipient_phone": "08120000000",
    "product_name": "Kaos Katun",
    "created_at": "2026-08-07T14:03:00+07:00"
  }
}

Header

Header	Tipe	Keterangan
X-Kurir-Signature	string	HMAC SHA-256 dari {timestamp}.{raw body} memakai signing secret webhook.
X-Kurir-Timestamp	string	Unix timestamp saat webhook dikirim.
X-Kurir-Event	string	Nama event, mis. order.delivered.
X-Kurir-Delivery	string	ID unik pengiriman webhook (untuk idempotensi).

Verifikasi Signature

Hitung ulang HMAC dari timestamp + raw body dan bandingkan dengan header (gunakan perbandingan konstan-waktu).

Node.js

const crypto = require('crypto');

function verify(rawBody, headers, secret) {
  const ts = headers['x-kurir-timestamp'];
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${ts}.${rawBody}`)
    .digest('hex');
  const got = headers['x-kurir-signature'];
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(got));
}

Python

import hmac, hashlib

def verify(raw_body: bytes, headers, secret: str) -> bool:
    ts = headers['X-Kurir-Timestamp']
    expected = hmac.new(
        secret.encode(),
        f'{ts}.'.encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, headers['X-Kurir-Signature'])

PHP

$ts = $_SERVER['HTTP_X_KURIR_TIMESTAMP'];
$raw = file_get_contents('php://input');
$expected = hash_hmac('sha256', $ts . '.' . $raw, $secret);
$ok = hash_equals($expected, $_SERVER['HTTP_X_KURIR_SIGNATURE']);

Pengiriman Ulang & Auto-Disable

• Balas dengan 2xx secepatnya untuk menandai webhook diterima.
• Response non-2xx atau timeout akan dicoba ulang dengan backoff bertahap.
• Endpoint yang terus gagal dapat dinonaktifkan otomatis; aktifkan kembali di halaman Webhooks.
• Gunakan X-Kurir-Delivery sebagai kunci idempotensi agar tidak memproses event ganda.

info

Kelola URL, secret, dan lihat riwayat pengiriman di Developers › Webhooks.