ТЗ на вебхуки для агента: подпись, повторы, дубли

Ты подключаешь оплату, форму или CRM, и сервис должен сообщать твоему приложению о событиях: «оплата прошла», «пришла заявка», «сделан возврат». Это вебхук: сервис сам отправляет запрос на адрес в твоём приложении. Агент сделает такой приём за несколько минут, и на тесте всё заработает. Проблемы начнутся позже. Провайдер отправит одно событие дважды, и клиент получит два доступа. Кто-то узнает адрес и пришлёт поддельный запрос «оплата прошла». Сервер будет недоступен минуту, и оплата потеряется.

webhooks.md описывает эти случаи заранее, по документации твоего провайдера и простыми словами. Агент читает файл и делает приём так, чтобы повтор, подделка и сбой ничего не ломали, а ты можешь проверить это сам по готовым тест-сценариям.

Что внутри webhooks.md

• 🔏Подпись

  Как приложение проверяет, что запрос пришёл от провайдера. Неподписанный запрос ничего не меняет.

• ⏱Защита от повтора (replay)

  Перехваченный старый запрос нельзя прислать снова: приложение проверяет время отправки и уже обработанные события.

• 🔁Повторная отправка (retry)

  Если приложение не ответило вовремя, провайдер пришлёт событие ещё раз. В файле записано, что отвечать и когда.

• 🧷Идемпотентность

  Одно событие, пришедшее три раза, выдаёт доступ один раз. Ключ — ID события, обработанные ID хранятся отдельно.

Как использовать

1. 1Найди документацию

   Раздел про вебхуки (уведомления, callback) у своего провайдера. Скопируй текст про формат запроса, подпись и повторную отправку.

2. 2Опиши события

   Какие события тебе нужны и что приложение делает по каждому: открыть доступ, закрыть доступ, создать заявку.

3. 3Собери webhooks.md

   Промпт шага 1 в новый чат. Сохрани ответ как webhooks.md в корне проекта.

4. 4Отдай агенту

   Промпт шага 2 в Claude Code или Cursor. Агент сначала покажет план и дождётся твоего «ок».

5. 5Прогони тесты

   Сценарии из раздела 9 файла, в тестовом режиме провайдера. Главный: одно событие дважды.

Какие сценарии повторов, задержек и потерь бывают с оплатами и как их воспроизвести, подробно разобрано в гайде Вебхуки оплаты: сценарии повторов, задержек и потери событий. Если агент работает в Cursor, общие правила для интеграций удобно держать в Cursor Rules для API и интеграций.

Рядом по теме: ТЗ на платную подписку, ТЗ на автоматизацию в n8n или Make и статья Как написать ТЗ для ИИ-агента — как вебхук нашего бота не заработал на сервере в России.

Что дальше

• Вебхуки оплаты: сценарии повторов, задержек и потери событий — глубже про то, что ломается в оплатах.
• Как тестировать код, который написал агент — чтобы проверять не только вебхуки.
• ТЗ на автоматизацию Make/n8n — если событие нужно передать в готовый сценарий.