웹훅 페이로드 레퍼런스
제출이 검증을 통과하면, 포워더는 당신이 구성한 웹훅 URL로 POST 하나를 보냅니다. 이 페이지는 그 요청의 정확한 계약입니다. 설정 안내는 호스팅 인증 설정하기를; 개념은 백엔드 없이 검증하기를 보세요.
요청 줄과 헤더
포워더는 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(당신이 제출한 필드)입니다:
{
"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가 아닌 응답, 시간 초과, 또는 연결 실패를 실패한 전달로 다루며, 실패한 전달은 재시도되지 않습니다. 전달 건강은 통계 페이지에서 추적하세요.
함께 보기
- 호스팅 인증 설정하기: 웹훅을 배선하고 테스트 전달 발사하기.
- 백엔드 없이 검증하기: 개념, 프라이버시 자세, 그리고 URL 안전 규칙.
- 호스팅 인증 통계: 전달 성공과 실패 읽기.