Referensi payload webhook

Saat sebuah kiriman lolos verifikasi, penerus mengirim satu POST ke URL webhook yang kamu konfigurasi. Halaman ini adalah kontrak persis untuk permintaan itu. Untuk panduan penyiapan, lihat siapkan verifikasi terhosting; untuk konsepnya, lihat verifikasi tanpa backend.

Baris permintaan dan header

Penerus mengirim sebuah POST dengan body JSON dan header-header ini:

Header	Nilai
`content-type`	`application/json`
`accept`	`application/json`
`user-agent`	`Caputchin-Forwarder/0.1`
`x-caputchin-test`	`1`, hadir hanya pada Uji pengiriman dasbor; absen pada kiriman nyata

Panggilan dikirim dengan pengalihan dimatikan dan timeout beberapa detik. Permintaan tak ditandatangani; kerahasiaan URL webhook itulah yang mengautentikasinya.

Body

Body adalah objek JSON dengan dua kunci tingkat-atas, caputchin (metadata verifikasi yang ditambahkan Caputchin) dan form (field yang kamu kirim):

{
  "caputchin": {
    "site_key": "cpt_pub_...",
    "session_id": "...",
    "game_id": "caputchin/games/leaf-memory",
    "score": 847,
    "duration_ms": 4200,
    "verified_at": 1748640000000
  },
  "form": {
    "email": "visitor@example.com",
    "message": "Hello!"
  }
}

Objek `caputchin`

Field	Tipe	Makna
`site_key`	string	Key publik `cpt_pub_...` asal kiriman.
`session_id`	string	Sebuah id sesi-verifikasi opaque, berguna untuk korelasi atau deduplikasi. Pada uji pengiriman ia berawalan `test_`.
`game_id`	string atau null	Game yang dimainkan pengunjung. Null saat verifikasi berjalan tanpa game.
`score`	number atau null	Skor game. Metadata yang diklaim klien untuk analitik, tak pernah sinyal kepercayaan. Null saat tak berlaku.
`duration_ms`	number atau null	Berapa lama pengunjung bermain game, dalam milidetik. Diklaim klien, bukan sinyal kepercayaan. Null saat tak berlaku (misalnya sebuah verifikasi tanpa game).
`verified_at`	number	Kapan Caputchin memverifikasi token, sebagai epoch Unix dalam milidetik.
`test`	boolean (opsional)	Hadir dan `true` hanya pada uji pengiriman dasbor. Absen pada kiriman nyata.

game_id, score, dan duration_ms masing-masing nullable pada kiriman nyata, jadi jaga terhadap null sebelum membacanya. Tak satu pun field caputchin adalah keputusan kepercayaan: kepercayaannya adalah bahwa permintaan tiba sama sekali, karena kiriman yang gagal verifikasi tak pernah diteruskan.

Objek `form`

form adalah objek datar dari field yang kamu kirim sebagai kunci string dan nilai string, persis seperti diposting, dengan satu perubahan: field caputchin-token disingkirkan sebelum pengiriman, jadi ia tak pernah muncul di sini. Penerus menerima field teks saja; sebuah kiriman yang membawa unggahan berkas ditolak sebelum pengiriman mana pun.

Apa yang harus dikembalikan handler-mu

Kembalikan status 2xx mana pun untuk mengakui penerimaan. Penerus memperlakukan respons non-2xx, sebuah timeout, atau kegagalan koneksi sebagai pengiriman yang gagal, dan pengiriman yang gagal tak dicoba-ulang. Lacak kesehatan pengiriman di halaman statistik.

Lihat juga

Siapkan verifikasi terhosting: sambungkan sebuah webhook dan tembakkan uji pengiriman.
Verifikasi tanpa backend: konsep, sikap privasi, dan aturan keamanan-URL.
Statistik verifikasi terhosting: membaca keberhasilan dan kegagalan pengiriman.