РУКОВОДСТВО · ОБНОВЛЕНО 2026-10-05
Webhook для фоновой AI-задачи: подпись, повторы и получение результата
Уведомление о завершении помогает отделить долгую обработку от HTTP-соединения. Разберём безопасный приём события и состояние задачи в приложении.
Webhook уведомляет приложение о событии, но не заменяет состояние задачи и проверку результата. Проверяйте подпись по исходному телу, сохраняйте событие устойчиво и обрабатывайте дубли по идентификатору. После уведомления получите результат разрешённым методом; при поддержке сервиса предусмотрите контроль статуса без webhook.
1. Опишите состояние задачи
Разделите принятие запроса, выполнение, успешное завершение, ошибку и отмену. Свяжите локальный job ID с идентификатором задачи сервиса и пользователем. Событие completed может означать завершение обработки, но приложение ещё должно проверить содержимое и сохранить результат. Не держите пользовательский HTTP-запрос открытым ради долгой генерации, если архитектура использует фоновый режим. При этом возможность фонового ответа должна быть явно поддержана методом; наличие обычного /responses не обещает background или webhook. Уточните также сроки доступности результата и допустимый порядок проверки статуса.
2. Проверьте подлинность уведомления
Используйте документированный алгоритм или поддерживаемую библиотеку для проверки подписи. Передайте исходное тело и нужные заголовки до преобразования JSON: повторная сериализация может изменить байты. Секрет webhook храните на сервере отдельно от пользовательского ввода. Проверяйте временные ограничения подписи и допустимые типы событий согласно контракту. Неверное событие не должно менять состояние задания. Подлинная подпись подтверждает источник, но не разрешает автоматически выполнить произвольный URL или команду из содержимого. Объём тела и время обработчика ограничьте явно, сохраняя безопасную диагностику отказа.
3. Сохраните событие до подтверждения
Для допустимого события устойчиво сохраните event ID и ссылку на задачу, затем подтверждайте приём по правилам сервиса. Долгую обработку вынесите в контролируемую очередь. Защитите запись от гонки двух одинаковых уведомлений уникальностью идентификатора. Отдельно обеспечьте идемпотентность итогового действия: событие и бизнес-операция не всегда имеют одинаковую границу повтора. Если запись не удалась, успешный HTTP-ответ может привести к потере события, поэтому выберите явное поведение для этой ошибки. Не обещайте доставку ровно один раз, если контракт и собственная обработка её не обеспечивают.
4. Получите и проверьте результат
Используйте сохранённый идентификатор задачи и разрешённый endpoint, а не адрес, произвольно присланный в payload. Проверьте принадлежность результата проекту и пользователю. Разберите текст, ошибку, отказ или неполный результат как отдельные состояния. Если сервис допускает получение статуса, используйте ограниченный polling для потерянных уведомлений и спорных переходов. Не запускайте новую генерацию только потому, что webhook задержался: первая задача могла уже завершиться. Отмена тоже требует проверки фактического состояния, а позднее событие не должно вернуть отменённую операцию к исполнению без предусмотренного правила.
5. Прогоните отказные сценарии
На локальных fixtures проверьте неверную подпись, изменённое тело, дубль, неизвестный job ID, сбой записи, позднее событие и отсутствие уведомления. Убедитесь, что повтор не отправляет второе сообщение и не списывает деньги повторно. Журнал хранит технический статус и идентификаторы, а не секрет подписи или весь документ. В Tokenmost сверяйте доступность конкретного фонового метода: статья не обещает управляемый webhook генерации. Условия хранения фона проверьте отдельно от store=false. Совместимость обработчика можно проверить без платной модели; реальная доставка сервиса остаётся отдельным этапом.
Частые вопросы
Webhook всегда содержит готовый текст?
Не обязательно. Событие может содержать идентификатор результата, который нужно получить отдельным разрешённым методом. Проверяйте конкретную схему уведомления.
Можно ли проверять подпись после JSON.parse?
Используйте исходное тело и заголовки согласно алгоритму сервиса. Изменение представления тела до проверки может нарушить соответствие подписи.
Почему приходит одно событие несколько раз?
Контракт может предусматривать повторную доставку при неуспешном подтверждении. Обработчик должен распознавать дубли и не повторять бизнес-действие.
Что делать, если уведомление не пришло?
Если метод поддерживает чтение статуса, проверьте исходную задачу ограниченным polling. Не создавайте новую генерацию вслепую из-за задержки webhook.