Apakah saya butuh webhook kalau sudah memakai Data API?

Tidak wajib, tetapi kebanyakan tim menjalankan keduanya. Data API menjawab tentang kunjungan yang sedang Anda lihat; webhook memberi tahu Anda tentang kunjungan yang tidak Anda lihat — serangan bot pukul tiga pagi, pengambilalihan akun pada sesi yang tidak ditonton siapa pun. Webhook juga membawa fase-fase lanjutan: verdict yang dikoreksi oleh bukti yang lebih lambat datang sebagai pengiriman baru.

Apa yang terjadi kalau endpoint saya mati?

Kami mencoba ulang pada tangga yang kian melebar — 5 detik, 30 detik, 2 menit, 10 menit, 30 menit, 2 jam, 6 jam — delapan percobaan yang tersebar kira-kira 4,4 sampai 8,7 jam, dan setiap jeda diacak agar percobaan ulang tidak datang sebagai satu gelombang. Restart yang berlangsung semenit tidak merugikan apa pun, dan sebuah webhook baru dinonaktifkan setelah rentetan kegagalan yang mencapai ambang sekaligus berlangsung setidaknya 15 menit berturut-turut.

Apakah saya harus memverifikasi kedua tanda tangan?

Memverifikasi HMAC sudah cukup untuk sebagian besar integrasi dan bekerja pada kedua skema payload. Tanda tangan platform Ed25519 adalah opsi yang lebih kuat — kunci publik alih-alih secret bersama — dan hadir bersama skema 2. Kalau verifier Anda mewajibkannya, biarkan pengiriman uji dari dashboard tetap lolos: secara rancangan mereka hanya HMAC, karena kunci privat platform tidak pernah meninggalkan node pengiriman.

Bisakah Data API dan webhook berbeda pendapat tentang kunjungan yang sama?

Keduanya bisa berbeda, dan itu bukan pertentangan. Data API menjawab dari catatan utama — apa yang diketahui saat halaman dimuat. Fase-fase berikutnya sampai kepada Anda sebagai pengiriman webhook dan tidak digabungkan kembali ke sana. Keduanya menjawab pertanyaan berbeda: apa yang kami ketahui pada momen itu, versus apa yang kami simpulkan seiring bukti terus berdatangan. Kalau Anda bertindak beberapa menit setelah kunjungan, percayai fase yang terakhir Anda terima.

Paket mana yang saya butuhkan?

Webhook mulai dari Pro — lima per workspace, 20 di Business, 100 di Enterprise. Data API mulai dari Pro ke atas. Guidance, kode alasan verdict, sinyal perilaku, dan data perangkat lintas-browser tersedia mulai Business ke atas.

Pengiriman Data

Data Anda, di tempat Anda mengambil keputusan

Setiap identifikasi bisa mencapai sistem Anda lewat dua jalan: dikirim ke server Anda begitu ia terjadi, atau Anda tarik sendiri pada detik Anda memutuskan. Kedua kanal membawa angka yang sama — dan itu dikunci oleh sebuah tes, bukan oleh janji.

Coba Gratis Pesan Demo

Dua kanal

Push atau pull

Webhook mendorong event kepada Anda saat kejadiannya berlangsung. Data API membuat Anda bisa bertanya tepat ketika Anda butuh jawaban. Kebanyakan tim menjalankan keduanya: webhook untuk mencatat dan bereaksi, Data API untuk memeriksa secara inline.

Webhook — push, secara real time

Kami mem-POST event JSON bertanda tangan ke endpoint Anda begitu sesuatu terjadi: seorang pengunjung teridentifikasi, sebuah pengambilalihan akun ditandai, sebuah serangan bot dimulai. Tidak ada yang perlu di-polling, tidak ada yang perlu dijadwalkan.

Paling cocok untuk: mencatat setiap kunjungan, bereaksi terhadap serangan, memasok gudang data atau SIEM Anda.

Latensi pengiriman p50 44–140 ms, dari event sampai ke endpoint Anda.

Data API — pull, sesuai permintaan

Sebuah API privat server-ke-server. Backend Anda melakukan autentikasi dengan secret key dan membaca persis apa yang kami ketahui tentang seorang pengunjung pada detik ia memutuskan — biasanya di dalam handler login atau checkout.

Paling cocok untuk: pemeriksaan inline sebelum Anda menagih kartu, menyetujui pendaftaran, atau membuka kunci akun.

Tersedia mulai paket Pro.

Webhook

Empat jenis event, satu amplop

Setiap pengiriman datang dalam amplop yang sama, dengan jenis event ada di body sekaligus di header X-Tracio-Event-Type — sehingga satu handler bisa merutekan keempatnya.

Pengunjung teridentifikasi

Event inti: sebuah kunjungan telah dinilai. Membawa ID pengunjung, browser dan OS, geo dan jaringan, verdict bot serta keputusan risiko. Dikirim bertahap — event utama saat halaman dimuat, lalu fase lanjutan atau koreksi ketika bukti yang lebih lambat mengubah verdict. Korelasikan antar-fase lewat requestId.

identification

Pengambilalihan akun

Detektor pengambilalihan akun menyala pada sebuah kunjungan: perangkat di balik akun yang sudah dikenal tidak lagi tampak seperti perangkat pemiliknya. Ia datang sebagai event tersendiri, lengkap dengan konteks akun, alih-alih bersembunyi di dalam body identifikasi.

account_takeover

Serangan bot

Lonjakan trafik otomatis di workspace Anda. Yang satu ini tidak punya kunjungan di baliknya — ini peringatan tingkat workspace, jadi blok kunjungan cukup absen dari body alih-alih datang sebagai cangkang kosong dengan skor nol.

attack_detected

Perubahan reputasi

Sebuah profil berpindah antar-pita reputasi. Amplopnya sama dengan peringatan serangan — event tingkat profil tanpa kunjungan, membawa pita yang baru dan yang sebelumnya.

reputation_changed

Sebuah pengiriman, dipangkas

Ini body dasarnya. Pro menambahkan visit velocity; Business menambahkan kode alasan verdict, sinyal perilaku, Guidance, dan data perangkat lintas-browser ke bentuk yang persis sama — blok baru bermunculan, jalur yang sudah ada tidak pernah berpindah.

JSON

{
  "version": 2,
  "event": "identification",
  "eventId": "req_8f21c4:primary",
  "requestId": "req_8f21c4",
  "phase": "primary",
  "visitorId": "3f9a1b2c4d5e6f70",
  "timestamp": "2026-07-30T12:00:00Z",
  "geo": { "country": "DE", "city": "Berlin", "timezone": "Europe/Berlin" },
  "network": { "vpn": true, "proxy": false, "tor": false, "datacenter": false },
  "bot": { "result": "human", "score": 12 },
  "identification": { "confidence": 0.97, "incognito": false },
  "decision": { "action": "suspicious", "riskScore": 65.9 }
}

Setiap permintaan membawa dua tanda tangan

X-Tracio-Signature adalah HMAC-SHA256 atas gabungan timestamp tanda tangan dan body permintaan mentah, dengan kunci berupa webhook secret Anda — ia membuktikan bahwa pengirim tahu secret yang Anda berdua pegang. X-Tracio-Signature-Ed25519 adalah tanda tangan platform: Anda memverifikasinya dengan kunci publik yang diambil dari endpoint well-known, jadi tidak ada rahasia apa pun yang perlu disimpan di sisi Anda. Timestamp adalah bagian dari isi yang ditandatangani, dan itulah yang membuat rekaman lama tidak berguna untuk diputar ulang.

Verifikasi terhadap byte permintaan mentah — JSON yang diserialisasi ulang mengubah byte-nya dan tanda tangannya tidak akan cocok. Percobaan ulang membawa X-Tracio-Event-Id yang sama, jadi lakukan deduplikasi berdasarkan itu.

Header pada setiap pengiriman

Text

X-Tracio-Signature:         t=1753444800,v1=5257a869e7ecebed...
X-Tracio-Signature-Ed25519: t=1753444800,kid=k1,v1=0Zx0M0n8...
X-Tracio-Event-Type:        identification
X-Tracio-Event-Id:          req_8f21c4:primary
X-Tracio-Delivery-Attempt:  1
X-Tracio-Payload-Version:   2

Keandalan

Dibangun agar tidak kehilangan event

Pengiriman berjalan di atas armada khusus, dan sumber kebenarannya adalah antrean — bukan memori sebuah proses. Itulah yang membuat at-least-once menjadi nyata: kalau satu node pengiriman mati di tengah jalan, event-nya masih ada di antrean dan node lain mengambilnya.

event per detik lewat satu webhook, naik dari sekitar 50 sebelum pembangunan ulang bulan Juli

44–140 mslatensi pengiriman p50 dari event sampai ke endpoint Anda

percobaan pengiriman pada tangga yang kian melebar, tersebar hingga 8,7 jam

dari 90.000 event terkirim dalam latihan yang mematikan satu node pengiriman di bawah beban

Percobaan ulang yang pas dengan gangguan nyata

5 detik, 30 detik, 2 menit, 10 menit, 30 menit, 2 jam, 6 jam. Percobaan pertama mendarat dalam satu menit, jadi restart singkat layanan Anda tidak merugikan apa pun. Setiap jeda dipilih acak antara separuh nilai yang tercantum dan nilai penuhnya, sehingga percobaan ulang tidak kembali sebagai satu gelombang setelah gangguan.

Penonaktifan otomatis yang tidak salah tembak

Sebuah webhook baru dimatikan ketika kegagalan mencapai ambang sekaligus sudah berlangsung setidaknya 15 menit berturut-turut — ledakan pengiriman yang mengantre saat restart tidak akan mematikan integrasinya. 410 Gone menonaktifkan seketika. Dashboard menampilkan alasannya, kode responsnya, dan tombol untuk mengaktifkan kembali.

Rotasi secret tanpa jeda

Setelah rotasi, kedua secret tetap berlaku selama 24 jam dan header membawa kedua tanda tangan, jadi cocok pada salah satunya sudah cukup. Anda memperbarui konfigurasi di dalam jendela itu alih-alih berkejaran dengan pergantian; “Revoke now” memangkas jendelanya ketika Anda memang ingin ia segera hilang.

Log pengiriman yang bisa Anda baca

Setiap percobaan — kode respons, durasi, teks error — terlihat per webhook di dashboard, bersebelahan dengan aksi uji yang mengirim contoh payload bertanda tangan ke endpoint Anda, sehingga Anda bisa memastikan verifier Anda sebelum tayang.

Data API

Bertanya pada saat Anda memutuskan

Sebuah API privat server-ke-server di api.tracio.ai. Backend Anda melakukan autentikasi dengan secret key dan membaca datanya sendiri. Ia sengaja tidak mengirim header CORS: sebuah secret key memberi akses ke semua isi workspace Anda dan tidak boleh sampai ke browser. Tersedia mulai paket Pro.

Metode	Path	Mengembalikan
GET	/v1/visitors/{visitorId}	Ringkasan pengunjung: pertama dan terakhir terlihat, jumlah kunjungan, IP dan negara unik, browser dan perangkat, riwayat risiko — plus sesi terbarunya.
GET	/v1/visitors/{visitorId}/sessions	Daftar sesi dengan paginasi kursor dan filter berdasarkan rentang tanggal, hasil bot, dan skor risiko minimum.
GET	/v1/visitors/{visitorId}/sessions/latest	Sesi terbaru sebagai satu objek tunggal, tanpa amplop daftar.
GET	/v1/sessions/{requestId}	Satu sesi tertentu. Sertakan visitorId bersamanya dan pencarian berjalan lewat indeks pengunjung alih-alih seluruh riwayat Anda.
GET	/v1/visitors/{visitorId}/velocity	Aktivitas dalam satu jendela — 1h, 24h, atau 7d: berapa banyak kunjungan, dari berapa banyak IP, dari berapa banyak negara, di bawah berapa banyak akun.

Memeriksa pengunjung saat checkout

Panggilan yang lazim: di dalam handler pembayaran Anda, sebelum Anda mengotorisasi kartu. Satu permintaan, satu jawaban, dan blok meta melaporkan jendela yang benar-benar Anda dapatkan — kalau Anda meminta enam bulan sementara paket Anda menyimpan 30 hari, ia mengembalikan 30 hari dan menyatakannya.

Permintaan

bash

# Inside your checkout handler, before you authorize the card
curl -s -H "Authorization: Bearer $TRACIO_SECRET_KEY" \
  "https://api.tracio.ai/v1/visitors/3f9a1b2c/velocity?window=24h"

Respons

JSON

{
  "window": "24h",
  "events": 128,
  "uniqueIps": 4,
  "uniqueCountries": 2,
  "uniqueAccounts": 1,
  "meta": { "plan": "business", "retentionDays": 30 }
}

Angka yang sama di mana-mana

Kunjungan yang berskor 65,9 di dashboard Anda juga berskor 65,9 di Data API dan 65,9 di body webhook. Dua rendering independen bisa saja menyimpang — skala adalah cara klasiknya, satu kanal memberi Anda 0,93 sementara yang lain mengatakan 93 — maka sebuah tes paritas membangun satu kunjungan, merender-nya lewat kedua kanal, lalu membandingkan kolom publiknya pada JSON mentah. Kesesuaian itu ditegakkan, bukan sekadar dinyatakan.

Guidance — Business ke atas

Saran, bukan sekadar angka

Skor memberi tahu apa yang kami lihat. Guidance memberi tahu apa yang perlu Anda lakukan, untuk empat keputusan yang sungguh-sungguh menyangkut uang — dihitung oleh aturan berversi, lengkap dengan alasannya.

Terima pembayarannya?

Menimbang risiko, reputasi penipuan, dan verdict bot sebelum Anda mengotorisasi kartu.

Terima pendaftarannya?

Menangkap akun sekali pakai sebelum ia ada — multi-akun dan reputasi paling berat bobotnya di sini.

Izinkan masuk?

Mengetat otomatis ketika detektor pengambilalihan akun menyala pada kunjungan tersebut.

Hitung konversinya?

Memisahkan referral asli dari referral ke diri sendiri atau bot berinsentif.

Kosakata empat kata

allowTidak ada yang perlu ditindaklanjuti.

challengeMinta faktor kedua.

reviewTahan untuk ditinjau manusia.

denyTolak langsung.

Setiap skenario mendapat satu dari empat jawaban, dan bersamanya dasar yang melandasinya — sumbu penentu dari kosakata tetap: bot, risiko, reputasi penipuan, perilaku, multi-akun, pengambilalihan akun, jaringan, pola afiliasi. Anda selalu tahu sumbu mana yang menggeser sarannya, tanpa pernah melihat nama sinyal, bobot, atau ambang.

Satu perhitungan, tiga kanal

Blok Guidance yang sama menumpang webhook, menjawab di Data API, dan tampil di kartu pengunjung dalam dashboard — satu kumpulan aturan, satu hasil, tanpa rekonsiliasi di sisi Anda. Bacalah saran untuk skenario Anda, bukan yang keseluruhan: yang keseluruhan hanyalah yang paling ketat dari keempatnya, ringkasan untuk dashboard dan bukan keputusan pembayaran. Versi aturan ikut dikirim di payload, jadi perubahan aturan adalah sesuatu yang Anda lihat, bukan sesuatu yang Anda simpulkan dari saran yang tiba-tiba bergeser.

JSON

"guidance": {
  "version": 1,
  "overall": "review",
  "payment": "review",
  "registration": "challenge",
  "login": "allow",
  "affiliate": "allow",
  "basis": ["risk", "fraud_reputation"]
}

Integrasi

Lima SDK di sisi depan, dua kanal di sisi belakang

Sisi browser hadir sebagai lima SDK — JavaScript murni, React, Vue 3, Angular, dan Svelte 5. Tidak ada SDK sisi server, dan itu disengaja: backend Anda terhubung lewat HTTP biasa melalui webhook bertanda tangan dan Data API. Verifikasi tanda tangan hanya selusin baris terhadap vektor referensi yang kami terbitkan, dan tidak ada tambahan apa pun yang harus terus Anda upgrade di pohon dependensi server Anda.

SDK browser

JavaScriptReactVue 3AngularSvelte 5

Jelajahi SDK Referensi API Dokumentasi webhook

FAQ

Pertanyaan yang sering diajukan

Rangkai dalam satu sore

Buat webhook di dashboard, arahkan ke endpoint Anda, lalu tekan Test. Verifikasi tanda tangannya terhadap vektor referensi kami, dan bagian sulitnya sudah lewat.

Coba Gratis Pesan Demo