Payload webhook affiliate

Webhook affiliate memberitahu sistem anda sendiri apabila seseorang menyertai program affiliate anda atau apabila sesuatu referral diluluskan. BCL menghantar HTTP POST dengan body JSON ke satu URL yang anda tetapkan untuk seluruh program. Page ini menyenaraikan setiap ruangan.

Untuk API BCL yang penuh, lihat rujukan API.

Tetapkan URL webhook anda

Webhook affiliate ditetapkan sekali untuk program anda, bukan untuk setiap payment form:

1. Pergi ke Affiliate → Settings.

2. Buka tab Webhook Settings.

   

3. On-kan Enable Webhook.

4. Masukkan Webhook URL anda.

5. Tandakan event yang anda mahu: Affiliate Joined, Referral Approved atau Payout Request.

6. Klik Save Webhook Settings.

   

Caution

Payout Request ada dalam senarai, tetapi versi BCL sekarang tidak menghantarnya. Jangan bina proses yang bergantung padanya buat masa ini.

Event

Body ialah objek JSON rata tanpa pembalut data. Key event memberitahu anda event yang mana:

event	Bila BCL menghantarnya
affiliate_joined	Seseorang menyertai program affiliate anda, termasuk apabila anda masih perlu meluluskan mereka.
referral_approved	Sesuatu referral diluluskan dan komisennya disahkan.
payout_request	Ada dalam senarai, tetapi tidak dihantar buat masa ini.

Setiap payload ada event, team_id, team_name, objek affiliate dan timestamp.

Affiliate joined

Ini ialah request affiliate_joined. Nilai-nilainya rekaan.

{
  "event": "affiliate_joined",
  "team_id": "9ce445a9-21f4-4e2a-b6fa-226dbb2a14f3",
  "team_name": "Contoh Trading",
  "affiliate": {
    "id": 12,
    "name": "Siti binti Ahmad",
    "email": "siti@example.com",
    "phone": "+60198765432"
  },
  "timestamp": "2026-09-27 12:46:53 +08"
}

Maksud setiap ruangan:

Ruangan	Jenis	Maksud
event	string	affiliate_joined.
team_id	string	ID akaun BCL anda.
team_name	string	Nama perniagaan anda dalam BCL.
affiliate.id	number	ID affiliate. Sama dengan affiliate_id dalam webhook payment form.
affiliate.name, affiliate.email, affiliate.phone	string	Butiran affiliate.
timestamp	string	Masa BCL menghantarnya, YYYY-MM-DD HH:MM:SS +08 (waktu Malaysia).

Referral approved

Request referral_approved menambah objek referral:

{
  "event": "referral_approved",
  "team_id": "9ce445a9-21f4-4e2a-b6fa-226dbb2a14f3",
  "team_name": "Contoh Trading",
  "affiliate": {
    "id": 12,
    "name": "Siti binti Ahmad",
    "email": "siti@example.com",
    "phone": "+60198765432"
  },
  "referral": {
    "id": 82,
    "form_title": "Online Cooking Class",
    "transaction_id": "01jnszhdng1z4mxqwsfqd27k5w",
    "order_number": "LINK-05912",
    "amount": "100.00",
    "commission_amount": "10.00",
    "status": "approved",
    "referral_source": "direct",
    "ip_address": "203.0.113.10",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
  },
  "timestamp": "2026-09-27 12:18:27 +08"
}

Maksud ruangan referral:

Ruangan	Jenis	Maksud
id	number	ID referral. Sama dengan affiliate_data.referral_id dalam webhook payment form.
form_title	string atau null	Tajuk payment form tempat jualan itu dibuat. Null jika referral itu tidak dipautkan kepada payment form.
transaction_id	string	ID dalaman jualan itu.
order_number	string	Nombor pesanan BCL bagi jualan itu.
amount	string	Amaun jualan yang menjadi asas komisen.
commission_amount	string	Komisen yang diperoleh.
status	string	Status referral, approved.
referral_source	string	Bagaimana pembeli sampai, contohnya direct.
ip_address, user_agent	string	Alamat IP dan browser pembeli semasa referral itu direkodkan.

Payout request

Sebagai rujukan, payload payout_request yang BCL sudah bina tetapi belum hantar menambah objek payout_request dengan id, total_amount, status, requested_at, referral_count dan senarai referrals. Setiap referral ada id, order_number, commission_amount, status dan transaction_id.

Perubahan daripada contoh lama

Bentuk payload sama seperti contoh lama. Bezanya, BCL tidak menghantar payout_request buat masa ini, walaupun event itu ditandakan.

Semak sama ada webhook itu tulen

BCL tidak menandatangani webhook. Tiada signature header atau shared secret. Untuk kekal selamat, guna URL yang sukar diteka, sahkan jualan itu melalui API BCL sebelum membayar komisen, dan pastikan sistem anda selamat menerima event yang sama dua kali.

BCL menghantar setiap event sekali dan tidak menghantar semula secara automatik jika penghantaran gagal. Sebarang respons 2xx dikira sebagai berjaya dihantar. Setiap cubaan disenaraikan di bawah Tools → Webhook Logs, dan anda boleh Resend dari situ.

Isu-isu biasa

Boleh saya hantar webhook affiliate ke lebih daripada satu URL?

Tidak boleh. Webhook affiliate hanya menerima satu Webhook URL untuk seluruh program. Jika beberapa sistem memerlukan data itu, halakan webhook ke satu endpoint yang forward data itu kepada sistem lain.

Bagaimana saya tahu jualan mana untuk sesuatu webhook referral_approved?

Guna referral.order_number. Ia ialah nombor pesanan BCL, nilai yang sama dengan record_id dalam webhook payment form.

Endpoint saya tidak berfungsi semasa seorang affiliate menyertai program. Boleh saya dapatkan webhook itu semula?

Boleh. Pergi ke Tools → Webhook Logs, cari baris yang gagal pada tab All dan klik Resend dalam menunya. Webhook affiliate tiada form, jadi ia tidak dipaparkan di bawah tab jenis form.

Artikel berkaitan

• On-kan program affiliate anda
• Bayar komisen affiliate
• Payload webhook payment form
• Jemput affiliate menyertai program anda