Mengirim penjualan dan data sendiri ke LinkHarbor

LinkHarbor juga menerima data dari luar. Untuk dua kasus ada endpoint khusus dengan secret sendiri – Anda tidak memerlukan kunci API untuk itu: sale callback melaporkan penjualan dari toko Anda, sehingga Anda bisa melihat di statistik tautan mana yang menghasilkan pendapatan. Integrasi “Custom (API)” membawa data langsung dari tool Anda sendiri ke halaman Anda sebagai widget dan bisa memicu notifikasi push.

#Sale callback: mencocokkan penjualan

Bagaimana ID klik (lt_click_id), pencocokan, dan pelaporan saling berkaitan dijelaskan di Mengaitkan konversi dan penjualan; di sini Anda menemukan semua kolom dan respons untuk developer. Singkatnya: saat LinkHarbor mengalihkan klik yang dihitung ke tujuan http atau https, LinkHarbor menambahkan parameter lt_click_id; toko Anda mengingatnya dan mengirimkannya kembali setelah pembelian.

Membuat rahasia callback

1. Buka “Callback & API”
2. Di kartu “Rahasia callback”, klik “+ Buat rahasia baru”
3. Jika mau, beri nama, misalnya “Callback toko”, lalu klik “Buat rahasia”
4. Segera salin rahasianya – rahasia hanya ditampilkan sekali

Siapa

Pemilik dan admin, mulai Creator Pro. Di Creator Free tertulis “Rahasia callback tersedia mulai dari Creator Pro.”

Berapa banyak

Hingga 5 rahasia per workspace, misalnya satu per toko.

“Edit”

Mengubah nama dan menyetel status ke “Aktif” atau “Nonaktif”. Dengan rahasia yang nonaktif, API menolak callback.

“↺ Rotasi”

Membuat rahasia baru; yang lama langsung berhenti berfungsi.

“Callback terakhir:”

Menunjukkan kapan rahasia terakhir berhasil dipakai.

Mengirim callback

curl -X POST https://dock.at-harbor.com/v1/callbacks/sale \
  -H "Content-Type: application/json" \
  -H "X-Callback-Secret: $LH_CALLBACK_SECRET" \
  -d '{
    "click_id": "3f1c2a9e-8d4b-4a51-9f0e-6b7c1d2e3f40",
    "order_id": "A-10023",
    "amount": "49.90",
    "currency": "EUR",
    "occurred_at": "2026-11-01T10:15:00Z"
  }'
# → {"ok":true,"conversion_id":123}

Tanda tangan opsional

Selain secret, Anda bisa mengirim header X-Callback-Signature. Header ini berisi sha256= dan tanda tangan HMAC-SHA256 dari body mentah dalam hex. Kuncinya bukan secret itu sendiri, melainkan hash SHA-256-nya dalam bentuk biner. Jika Anda mengirim header ini, isinya harus benar – jika tidak, callback ditolak.

<?php
$body = json_encode($payload);
$key  = hash('sha256', getenv('LH_CALLBACK_SECRET'), true); // hash biner dari secret
$sig  = 'sha256=' . hash_hmac('sha256', $body, $key);
// Header: X-Callback-Secret dan X-Callback-Signature: $sig, body: $body

Tempat Anda melihat penjualan

Penjualan yang dilaporkan muncul sebagai konversi di statistik Anda, lihat Mengaitkan konversi dan penjualan. Lewat API, Anda membacanya dengan read:stats di /v1/stats/…/conversions/breakdown.

#Custom (API): data langsung Anda sendiri

Dengan integrasi “Custom (API)”, program apa pun yang bisa mengirim permintaan HTTP – plugin server game, bot, skrip cron – bisa mengirim data ke LinkHarbor. Data itu menjadi widget langsung di halaman Anda, dan aturan push bisa memberi tahu pengikut Anda.

Menghubungkan

1. Buka “Integrasi” di workspace
2. Pilih “Custom (API)” dan masukkan nama
3. Setelah terhubung, dialog menampilkan “URL ingest” dan “Secret” (dengan “Tampilkan secret”)
4. Simpan keduanya di tool Anda

Integrasi tersedia mulai Creator Pro. Hanya pemilik dan admin yang bisa melihat URL ingest dan secret, termasuk nanti di tampilan detail integrasi. Memutus dan menghubungkan ulang membuat secret baru. Cara menghubungkan integrasi secara umum dijelaskan di Menghubungkan integrasi.

Mengirim data

curl -X POST "$INGEST_URL" \
  -H "Authorization: Bearer $INGEST_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "player.joined",
    "event_id": "join-2026-11-01T20:01:02Z-steve",
    "data": { "player": "Steve" },
    "state": {
      "type": "game_server",
      "name": "Survival SMP",
      "online": true,
      "players_online": 3,
      "players_max": 20
    }
  }'
# → {"ok":true,"event_id":4711,"duplicate":false,"event_type":"player.joined"}

event

Nama event bebas, misalnya player.joined. Nama ini diubah menjadi huruf kecil dan merupakan nama yang ditanggapi aturan push. Tanpa event, event-nya bernama state.updated.

event_id

Kunci opsional yang mencegah pemrosesan ganda. Jika event_id yang sama dikirim lagi, LinkHarbor merespons dengan duplicate: true dan tidak melakukan apa pun.

data

Nilai untuk placeholder di teks push, misalnya {player}. Hingga 40 kunci, hanya nilai sederhana.

state

Status lengkap widget. Status ini sepenuhnya menggantikan yang sebelumnya. type bernilai game_server (kartu server game) atau status (kartu status).

Alih-alih Authorization: Bearer, Anda juga bisa mengirim secret di header X-LinkHarbor-Secret. 120 panggilan per menit diizinkan per alamat IP. Jika mau, Anda menandatangani body: header X-LinkHarbor-Signature berisi sha256= dan tanda tangan HMAC-SHA256 dari body mentah dengan secret sebagai kunci. Jika Anda mengirimnya, isinya harus benar.