Настрой размещённую проверку с тестовым ящиком

К концу этого руководства у тебя будет рабочая контактная форма, чьи отправки проверяет Caputchin и доставляет на вебхук, и ты увидишь, как проверенная отправка приземляется в тестовый ящик, который ты можешь осмотреть. Мы сначала используем webhook.site как назначение, потому что он показывает тебе точную нагрузку, которую шлёт Caputchin, до того как ты привяжешься к своему собственному эндпоинту.

Тебе нужен тариф Alpha, Troop или Apex (размещённой проверки нет на Solo), ключ сайта и страница, где ты можешь редактировать HTML формы. Если ты ещё не добавил виджет на страницу, сначала добавь виджет; это руководство предполагает рабочий <caputchin-widget>.

1. Получи тестовый ящик

Открой webhook.site в новой вкладке. Он сразу даёт тебе уникальный URL, который выглядит как https://webhook.site/#!/<uuid>, и соответствующий URL доставки вида https://webhook.site/<uuid>. Скопируй URL доставки (тот, что без #!/). Оставь вкладку открытой; каждый запрос, который он получает, появляется там в реальном времени.

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

2. Включи размещённую проверку

В панели открой ключ сайта и перейди на его страницу Размещённая проверка.

Вставь URL доставки webhook.site в поле URL вебхука.
Оставь email пустым пока что.
Сохрани.

Тебе пока не нужно перекидывать переключатель включена. Следующий шаг использует Тест доставки, который работает на сохранённом назначении независимо от того, включена ли размещённая проверка, так что ты можешь подтвердить подключение до выхода в эфир.

3. Отправь тестовую доставку

На той же странице используй Тест доставки. Caputchin шлёт синтетическую отправку прямо в твоё назначение, не запуская игру и не проверяя токен, так что это чистая проверка подключения назначения.

Переключись на вкладку webhook.site. Новый POST появляется в течение секунды-другой. Его тело JSON выглядит так:

{
  "caputchin": {
    "site_key": "cpt_pub_...",
    "session_id": "test_...",
    "game_id": null,
    "score": null,
    "duration_ms": null,
    "verified_at": 1748640000000,
    "test": true
  },
  "form": {
    "email": "test@example.com",
    "message": "Test submission from your Caputchin dashboard."
  }
}

Маркер "test": true сообщает твоему обработчику, что это был тест из панели, а не настоящий посетитель; он отсутствует на реальных отправках. Если ты видишь эту нагрузку, назначение работает. Если ничего не приходит, перепроверь, что ты скопировал URL доставки (а не URL просмотрщика #!/) и сохранил его.

4. Направь свою форму на пересыльщик

Теперь сделай так, чтобы настоящая отправка прошла через Caputchin. Единственное изменение в твоей форме это её action: вместо твоего собственного бэкенда она отправляется на URL пересыльщика, который ключ сайта показывает тебе на странице Размещённая проверка.

<form action="https://caputchin.com/api/forward/cpt_pub_..." method="POST">
  <input name="email" type="email" />
  <input name="message" />
  <caputchin-widget sitekey="cpt_pub_..."></caputchin-widget>
  <button type="submit">Send</button>
</form>

Больше ничего не меняется. Виджет всё ещё вставляет скрытое поле caputchin-token, когда посетитель проходит испытание; пересыльщик читает это поле, проверяет его и убирает до доставки остального в твоё назначение.

5. Включи размещённую проверку

Вернувшись на страницу Размещённая проверка, перекинь переключатель включена и сохрани. Пересыльщик отклоняет отправки для ключа сайта, который не включён, так что этот переключатель и есть то, что делает шаг 4 живым.

6. Отправь форму по-настоящему

Загрузи свою страницу, заполни форму, пройди испытание и отправь. Следи за вкладкой webhook.site: приходит второй POST, на этот раз без поля test и с настоящими метаданными проверки.

{
  "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 проверяет, твоё назначение получает только проверенную отправку. Отправка, которая не проходит проверку (отсутствующий, просроченный или повторно использованный токен), вообще не достигает твоего назначения.

Обращайся с блоком caputchin так, как обращался бы с вердиктом бэкенда: game_id, score и duration_ms это заявленные клиентом метаданные для твоей аналитики, а не сигнал доверия. Решение о доверии это сам факт, что отправка вообще пришла. Любое из этих трёх может быть null на реальной отправке (например проверка без игры), так что страхуйся от null до того, как их читать.

7. Попробуй и email-назначение

webhook.site также даёт каждому ящику адрес email, так что ты можешь протестировать доставку email тем же способом. На странице webhook.site найди уникальный email-адрес своего ящика и скопируй его; на момент написания он выглядит как <your-inbox-id>@emailhook.site, но проверь на странице текущую форму, поскольку этой деталью владеет webhook.site. Затем:

Вернувшись на страницу Размещённая проверка, вставь этот адрес в поле email.
Сохрани и снова используй Тест доставки.

Письмо приходит в ящик webhook.site рядом с запросами: обычное сообщение, несущее поля формы, и подвал, отмечающий, что Caputchin проверил отправку. Email доставляется через email-провайдера Caputchin, так что оно может приземляться чуть дольше, чем POST вебхука. С заданными и URL вебхука, и адресом email одна отправка разветвляется на оба и считается доставленной, если удаётся хотя бы один.

8. Подставь своё настоящее назначение

Когда тестовый ящик показал тебе, чего ждать, замени его своим собственным:

Твой собственный вебхук. Помести URL своего эндпоинта в поле URL вебхука. Это должен быть публичный https-URL; Caputchin отказывает URL, которые разрешаются в приватные, петлевые или облачно-метаданные адреса, и не будет следовать редиректам. Твой обработчик получает ровно ту форму JSON, что выше. Доставки не подписываются, так что держи URL в секрете, поскольку его секретность и есть то, что аутентифицирует вызов.
Email вместо или вдобавок. Помести свой собственный адрес в поле email, тем же способом, что ты тестировал выше. Ты можешь запустить оба сразу, например вебхук для обработки плюс копию на email себе.

Отправь ещё одну настоящую отправку против живого назначения для подтверждения, и ты готов.

Куда дальше

Статистика размещённой проверки: следи за здоровьем доставки со временем.
Размещённая проверка: концепции, позиция приватности и что намеренно оставлено за бортом.
Проверь на своём бэкенде: альтернатива, если ты позже добавишь сервер.

Настрой размещённую проверку с тестовым ящиком

На этой странице