---
type: reference
title: Справочник нагрузки вебхука
summary: Точный запрос, который получает вебхук размещённой проверки, каждое поле в теле и заголовки, которые шлёт Caputchin.
---

Когда отправка проходит проверку, пересыльщик шлёт один `POST` на твой настроенный URL вебхука. Эта страница это точный контракт для этого запроса. Для прохождения настройки смотри [настрой размещённую проверку](/docs/hosted-verification/set-up); для концепции смотри [проверяй без бэкенда](/docs/hosted-verification/overview).

## Строка запроса и заголовки

Пересыльщик шлёт `POST` с телом JSON и этими заголовками:

| Заголовок | Значение |
|---|---|
| `content-type` | `application/json` |
| `accept` | `application/json` |
| `user-agent` | `Caputchin-Forwarder/0.1` |
| `x-caputchin-test` | `1`, присутствует только на **Тест доставки** из панели; отсутствует на реальных отправках |

Вызов отправляется с отключёнными редиректами и тайм-аутом в несколько секунд. Запрос не подписывается; секретность 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` | строка | Публичный ключ `cpt_pub_...`, с которого пришла отправка. |
| `session_id` | строка | Непрозрачный id сессии проверки, полезен для корреляции или дедупликации. На тестовой доставке он с префиксом `test_`. |
| `game_id` | строка или null | Игра, в которую играл посетитель. Null, когда проверка шла без игры. |
| `score` | число или null | Счёт игры. Заявленные клиентом метаданные для аналитики, никогда не сигнал доверия. Null, когда неприменимо. |
| `duration_ms` | число или null | Сколько посетитель провёл за игрой, в миллисекундах. Заявлено клиентом, не сигнал доверия. Null, когда неприменимо (например проверка без игры). |
| `verified_at` | число | Когда Caputchin проверил токен, как Unix-эпоха в миллисекундах. |
| `test` | булево (опционально) | Присутствует и `true` только на тестовой доставке из панели. Отсутствует на реальных отправках. |

`game_id`, `score` и `duration_ms` каждое nullable на реальной отправке, так что страхуйся от null до того, как их читать. Ни одно из полей `caputchin` не является решением о доверии: доверие в том, что запрос вообще пришёл, потому что отправка, которая не проходит проверку, никогда не пересылается.

### Объект `form`

`form` это плоский объект твоих отправленных полей как строковые ключи и строковые значения, ровно как отправлено, с одним изменением: поле `caputchin-token` убирается до доставки, так что оно никогда здесь не появляется. Пересыльщик принимает только текстовые поля; отправка, несущая загрузку файла, отклоняется до любой доставки.

## Что должен возвращать твой обработчик

Возвращай любой статус `2xx`, чтобы подтвердить получение. Пересыльщик трактует ответ не-`2xx`, тайм-аут или сбой соединения как сбойную доставку, а сбойная доставка не повторяется. Отслеживай здоровье доставки на странице [статистики](/docs/hosted-verification/statistics).

## См. также

- [Настрой размещённую проверку](/docs/hosted-verification/set-up): подключи вебхук и выпусти тестовую доставку.
- [Проверяй без бэкенда](/docs/hosted-verification/overview): концепция, позиция приватности и правила безопасности URL.
- [Статистика размещённой проверки](/docs/hosted-verification/statistics): чтение успехов и сбоев доставки.