Как настроить webhook в OpenAI API и не потерять событие

1. Отдельный тестовый проект или среду, где ошибка не затронет клиентов.
2. Один обезличенный пример данных и ожидаемый результат в двух-трёх предложениях.
3. Журнал: время, версия модели или интеграции, идентификатор запроса, итоговый статус.
4. Правило остановки: какие ответы нельзя публиковать или выполнять автоматически.

Не отправляйте в запросы ключи доступа, полные договоры с персональными данными или внутренние инструкции, если у вас нет разрешения и понятной политики обработки. Чем точнее входные данные, тем легче отличить полезный ответ от правдоподобного, но неверного.

Порядок работы

В панели проекта создайте webhook, укажите HTTPS-адрес обработчика и подпишитесь только на нужные типы событий. В обработчике сначала проверьте подпись по сырому телу запроса, затем сохраните идентификатор события как ключ идемпотентности и лишь потом запускайте бизнес-логику.

После каждого шага сохраняйте минимально необходимый след: идентификатор операции, версию входных данных и причину решения. Не полагайтесь на текстовое «готово» от модели как на техническое подтверждение. Если интеграция сообщает об ошибке, сначала разберите статус и документацию, а уже затем меняйте промпт или код.

Готовый шаблон запроса

Сгенерируй JSON-спецификацию обработчика webhook: поля event_id, type, received_at, payload и status. Добавь правила: неизвестный тип — в журнал, повторный event_id — без повторной операции.

Шаблон специально ограничивает модель: он задаёт формат, разрешает честно сообщить об отсутствии данных и запрещает додумывать. Перед использованием замените абстрактные поля на свой тип документа или операции. Если результат будет читать человек, попросите короткие основания, а не длинное объяснение рассуждений.

Пример и проверка результата

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

Проверяйте результат по пяти пунктам:

1. Использованы ли только переданные и явно разрешённые данные.
2. Выполнен ли обещанный формат: поля, типы, длина, язык.
3. Отмечены ли пропуски, неоднозначности и рискованные действия.
4. Не изменился ли бизнес-смысл при сокращении или классификации.
5. Можно ли повторить запуск и объяснить, почему система приняла решение.

Если хотя бы один пункт не проходит, не маскируйте проблему красивой формулировкой. Верните результат на ручную проверку, исправьте вход или контракт и повторите тест на том же примере.

Типичные ошибки