---
type: reference
title: Referensi payload webhook
summary: Permintaan persis yang diterima sebuah webhook verifikasi-terhosting, setiap field di body, dan header yang dikirim Caputchin.
---

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](/docs/hosted-verification/set-up); untuk konsepnya, lihat [verifikasi tanpa backend](/docs/hosted-verification/overview).

## 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):

```json
{
  "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](/docs/hosted-verification/statistics).

## Lihat juga

- [Siapkan verifikasi terhosting](/docs/hosted-verification/set-up): sambungkan sebuah webhook dan tembakkan uji pengiriman.
- [Verifikasi tanpa backend](/docs/hosted-verification/overview): konsep, sikap privasi, dan aturan keamanan-URL.
- [Statistik verifikasi terhosting](/docs/hosted-verification/statistics): membaca keberhasilan dan kegagalan pengiriman.