Почему ваш колбэк задачи hiapi не срабатывает и как это исправить

Почему ваш колбэк задачи hiapi не срабатывает

Вы отправили задачу в POST https://api.hiapi.ai/v1/tasks с объектом callback; задача завершилась (при GET /v1/tasks/{taskId} вы видите status: "success"), но ваша точка входа так и не получила уведомление о терминальном состоянии. На ваш сервер не пришёл ни один запрос. Никаких повторных попыток. В логах пусто.

Колбэки hiapi доставляются в виде HTTPS POST между серверами извне вашей сети. Если на этом пути что-то ломается — URL недоступен из публичного интернета, TLS не согласуется, ваш обработчик не возвращает 2xx достаточно быстро, или проверка подписи на вашей стороне отклоняет запрос — то с точки зрения вашего приложения это уведомление «молчит». Хорошая новость: почти всегда это одна из нескольких ошибок конфигурации, и каждую легко проверить.

Распространённые причины (по вероятности)

1. URL колбэка недоступен из публичного интернета. localhost, 127.0.0.1, IP внутри вашего VPC или просроченный туннель ngrok — hiapi до них не достучится.
2. Проблемы с HTTPS / TLS. Самоподписанный сертификат, просроченный сертификат, отсутствие промежуточного сертификата или несовпадение имени хоста. hiapi отправляет POST только на URL, начинающиеся с https://, и проверяет цепочку сертификатов.
3. Ваш обработчик не возвращает 2xx в пределах тайм-аута. Если вы同步но выполняете длительные операции (запись в базу данных, скачивание изображений, отправка уведомлений) внутри обработчика колбэка, запрос истечёт по тайм-ауту раньше, чем вы вернёте 200. С точки зрения hiapi это неудачная доставка.
4. Вы никогда не регистрировали Webhook Sign Key, а ваш обработчик отклоняет неподписанные запросы. Если в Settings не сгенерирован ключ подписи, hiapi доставляет тело запроса без заголовка подписи — любое middleware проверки, которое вы написали, сочтёт запрос недействительным и отбросит его.
5. При отправке пропущен объект callback. Он необязателен. Если вы не включили его в POST /v1/tasks, то и срабатывать нечему. Вместо этого вам придётся опрашивать GET /v1/tasks/{taskId}.
6. Задача всё ещё выполняется. Колбэк срабатывает только в терминальном состоянии (success или fail). Пока status равен queued, handling или archiving, колбэк ещё не отправляется.
7. Хост URL колбэка в списке запретов / корпоративный файрвол блокирует исходящий трафик к нему. Менее распространено, но стоит проверить, если вы работаете в строгой периметровой сети.

Как исправить: контрольный список из 7 шагов

1. Убедитесь, что задача действительно достигла терминального состояния. curl -H "Authorization: Bearer $HIAPI_KEY" https://api.hiapi.ai/v1/tasks/tk-hiapi-.... Если status равен queued или handling, колбэк ещё не сработал — подождите, не начинайте отладку.
2. Убедитесь, что вы отправили объект callback. Перечитайте тело запроса, отправленного в POST /v1/tasks. Если callback отсутствует, вот и ответ — добавьте его и отправьте заново, либо перейдите на опрос.
3. Проверьте URL колбэка из публичного интернета. С любой машины вне вашей сети (телефон с мобильным интернетом, облачный shell, онлайн-инструмент curl) выполните curl -i -X POST https://your.domain.example/hiapi/callback -d '{}' -H "Content-Type: application/json". Вы должны получить от своего сервера HTTP-ответ 2xx. Если получите отказ в соединении, DNS-ошибку или любой ответ не 2xx, сначала исправьте это.
4. Проверьте цепочку TLS-сертификатов. curl -vI https://your.domain.example/hiapi/callback 2>&1 | grep -i 'ssl\|cert'. Ищите SSL certificate problem. Если видите эту ошибку, установите полную цепочку сертификатов (листовой + промежуточный) или используйте управляемые сертификаты (Let's Encrypt, CDN, ACM).
5. Возвращайте 200 немедленно, а затем обрабатывайте асинхронно. Внутри вашего обработчика: записать payload в очередь / таблицу, вернуть 200 OK, а затем выполнять работу в фоновом worker'е. Не позволяйте ответу блокироваться медленными нисходящими вызовами.
6. Сгенерируйте Webhook Sign Key и унифицируйте проверку. Перейдите в /en/dashboard/settings → Webhook Sign Key → Generate, сохраните ключ. Если ваш обработчик проверяет подпись, используйте сохранённый ключ; если не проверяет, временно отключите проверку, убедитесь в нормальной доставке и затем включите снова.
7. Проверьте /en/dashboard/logs. Журнал вызовов покажет запрос и его терминальное состояние. Сопоставить request_id из журнала вызовов с тем, что фактически получил ваш сервер (если получил), — самый быстрый способ понять, «покинул ли колбэк hiapi» и «дошёл ли колбэк до моего сервера».

Минимальный пример для проверки

Используйте следующее для сквозной проверки вашего API-ключа, пути создания задачи и точки входа колбэка. Выберите быструю модель изображений для smoke-теста; согласно публичной документации, ID моделей включают суффикс возможностей:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/text-to-image",
    "input": {"prompt": "a cute cat"},
    "callback": {"url": "https://your.domain.example/hiapi/callback"}
  }'

Вы должны сразу получить JSON-ответ с taskId вида tk-hiapi-.... Затем, как только задача перейдёт в success или fail, следите за логами сервера на наличие входящего POST на /hiapi/callback. Если сам шаг создания задачи возвращает 401 Unauthorized, проблема в ключе — см. Почему hiapi возвращает 429 (и что с этим делать), чтобы понять, как работает механика конверта ошибок hiapi (одна и та же структура hiapi_error применяется ко всем кодам состояния).

Связанные ссылки

• API Keys — проверьте, что ваш ключ действителен и имеет правильные области权限
• Settings — сгенерируйте или обновите ваш Webhook Sign Key
• Call Logs — убедитесь, что hiapi отправил колбэк, и посмотрите статус ответа
• API Reference — полные спецификации POST /v1/tasks и GET /v1/tasks/{id}
• Ограничение скорости hiapi 429 — подробный разбор конверта ошибок для связанных проблем «я получаю статус, но не получаю колбэк»

FAQ

Повторяет ли hiapi неудачные колбэки? Колбэк считается доставленным только тогда, когда ваша точка входа возвращает ответ 2xx. Если ваш обработчик возвращает 5xx, истекает по тайм-ауту или TLS-рукопожатие не удаётся, считайте колбэк недоставленным. Самый надёжный подход: для любой задачи, отправленной с колбэком, всегда используйте опрос GET /v1/tasks/{taskId} как запасной вариант. Так даже единичный сбой на пути колбэка не приведёт к потере результата.

Можно ли использовать HTTP вместо HTTPS для URL колбэка? Нет. Принимаются только URL, начинающиеся с https://. Если вы тестируете локально, используйте туннель, который завершает TLS за вас (Cloudflare Tunnel, ngrok, tailscale funnel), и направьте колбэк на публичный HTTPS-эндпоинт.

Почему мой обработчик получил тело запроса, но проверка подписи не прошла? Либо (a) вы сгенерировали Webhook Sign Key после отправки задачи — запрос подписан старым ключом (или без ключа) — поэтому перегенерируйте, сохраните и отправьте новую задачу; либо (b) ваш код проверки строит каноническую строку не так, как hiapi. Запишите точные байты тела запроса, полученного вашим сервером, и повторно выполните HMAC по этим точным байтам без какой-либо повторной JSON-сериализации.

taskId показывает success, но я не получил ни колбэк, ни URL результата. Повторно запросите GET /v1/tasks/{taskId} и посмотрите массив output. URL в output[*].url имеют ограничение по времени (expireAt); скачивайте немедленно. Доставка колбэка и срок действия URL — две независимые проблемы; даже без колбэка GET-эндпоинт является источником истины.

Я вижу колбэк в /en/dashboard/logs, но мой сервер его не залогировал. Это указывает на проблему в вашем периметре, а не в hiapi. Частые причины: правила CDN / WAF блокируют POST-запросы без распознаваемого User-Agent вашей команды, allow-list IP на файрволе или обратный прокси, переписывающий путь. Разрешите входящий POST на файрволе и запустите проверку снова.

Считается ли URL колбэка в лимитах скорости моего аккаунта? Нет. Колбэки — это доставка от hiapi к вам, она не связана с вашим бюджетом скорости POST /v1/tasks.