---
type: reference
title: 웹훅 페이로드 레퍼런스
summary: 호스팅 인증 웹훅이 받는 정확한 요청, 본문의 모든 필드, 그리고 Caputchin이 보내는 헤더.
---

제출이 검증을 통과하면, 포워더는 당신이 구성한 웹훅 URL로 `POST` 하나를 보냅니다. 이 페이지는 그 요청의 정확한 계약입니다. 설정 안내는 [호스팅 인증 설정하기](/docs/hosted-verification/set-up)를; 개념은 [백엔드 없이 검증하기](/docs/hosted-verification/overview)를 보세요.

## 요청 줄과 헤더

포워더는 JSON 본문과 이 헤더들을 둔 `POST`를 보냅니다:

| 헤더 | 값 |
|---|---|
| `content-type` | `application/json` |
| `accept` | `application/json` |
| `user-agent` | `Caputchin-Forwarder/0.1` |
| `x-caputchin-test` | `1`, 대시보드 **Test delivery**에만 있음; 진짜 제출에는 없음 |

호출은 리디렉션이 비활성화되고 몇 초의 시간 초과로 보내집니다. 요청은 서명되지 않습니다; 웹훅 URL의 비밀성이 그것을 인증하는 것입니다.

## 본문

본문은 두 최상위 키를 둔 JSON 객체로, `caputchin`(Caputchin이 더하는 검증 메타데이터)과 `form`(당신이 제출한 필드)입니다:

```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!"
  }
}
```

### `caputchin` 객체

| 필드 | 타입 | 의미 |
|---|---|---|
| `site_key` | string | 제출이 온 공개 `cpt_pub_...` 키. |
| `session_id` | string | 불투명한 검증 세션 id로, 상관 관계나 중복 제거에 유용. 테스트 전달에서는 `test_` 접두사가 붙음. |
| `game_id` | string 또는 null | 방문자가 한 게임. 검증이 게임 없이 돌았을 때 null. |
| `score` | number 또는 null | 게임 점수. 분석용으로 클라이언트가 주장한 메타데이터, 결코 신뢰 신호 아님. 해당 없을 때 null. |
| `duration_ms` | number 또는 null | 방문자가 게임을 하는 데 들인 시간, 밀리초. 클라이언트가 주장함, 신뢰 신호 아님. 해당 없을 때 null(예를 들어 게임 없는 검증). |
| `verified_at` | number | Caputchin이 토큰을 검증한 때, 밀리초 단위 Unix epoch. |
| `test` | boolean (선택) | 대시보드 테스트 전달에만 있고 `true`. 진짜 제출에는 없음. |

`game_id`, `score`, `duration_ms`는 각각 진짜 제출에서 nullable이니, 그것들을 읽기 전에 null을 막으세요. `caputchin` 필드 중 어떤 것도 신뢰 결정이 아닙니다: 신뢰는 요청이 도착했다는 것 자체인데, 검증에 실패하는 제출은 결코 전달되지 않기 때문입니다.

### `form` 객체

`form`은 당신이 제출한 필드를, post된 그대로, 문자열 키와 문자열 값의 평평한 객체로 둡니다, 한 가지 변경과 함께: `caputchin-token` 필드는 전달 전에 제거되니, 여기 결코 나타나지 않습니다. 포워더는 텍스트 필드만 받습니다; 파일 업로드를 지닌 제출은 어떤 전달도 있기 전에 거부됩니다.

## 당신의 핸들러가 무엇을 돌려줘야 하는가

수신을 확인하려면 어떤 `2xx` 상태든 돌려주세요. 포워더는 `2xx`가 아닌 응답, 시간 초과, 또는 연결 실패를 실패한 전달로 다루며, 실패한 전달은 재시도되지 않습니다. 전달 건강은 [통계](/docs/hosted-verification/statistics) 페이지에서 추적하세요.

## 함께 보기

- [호스팅 인증 설정하기](/docs/hosted-verification/set-up): 웹훅을 배선하고 테스트 전달 발사하기.
- [백엔드 없이 검증하기](/docs/hosted-verification/overview): 개념, 프라이버시 자세, 그리고 URL 안전 규칙.
- [호스팅 인증 통계](/docs/hosted-verification/statistics): 전달 성공과 실패 읽기.