Справочник нагрузки вебхука

Когда отправка проходит проверку, пересыльщик шлёт один POST на твой настроенный URL вебхука. Эта страница это точный контракт для этого запроса. Для прохождения настройки смотри настрой размещённую проверку; для концепции смотри проверяй без бэкенда.

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

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

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

Вызов отправляется с отключёнными редиректами и тайм-аутом в несколько секунд. Запрос не подписывается; секретность 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`	строка	Публичный ключ `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, тайм-аут или сбой соединения как сбойную доставку, а сбойная доставка не повторяется. Отслеживай здоровье доставки на странице статистики.

См. также

Настрой размещённую проверку: подключи вебхук и выпусти тестовую доставку.
Проверяй без бэкенда: концепция, позиция приватности и правила безопасности URL.
Статистика размещённой проверки: чтение успехов и сбоев доставки.