hiapi タスクのコールバックが発火しないのはなぜか、そして修正方法

hiapi タスクのコールバックが発火しないのはなぜか

あなたは callback オブジェクトを付けてタスクを POST https://api.hiapi.ai/v1/tasks に送信しました。タスクは完了した（GET /v1/tasks/{taskId} を実行すると status: "success" が見える）のに、エンドポイントには終了通知が一度も届いていません。サーバーにリクエストは一切届かず、リトライもなく、ログにも何も残っていません。

hiapi のコールバックは、あなたのネットワーク外部からサーバー間の HTTPS POST として配信されます。この経路のどこかで問題が起きていると——URL が公網からアクセスできない、TLS がネゴシエーションできない、ハンドラーが十分素早く 2xx を返さない、あるいはあなた側の署名検証がリクエストを拒否した——アプリケーションの視点からは、この通知は「サイレント」に消えたように見えます。朗報は、これがほぼ常に少数の設定ミスのいずれかであり、どれも簡単に検証できることです。

よくある原因（可能性の高い順）

1. コールバック URL が公網からアクセスできない。 localhost、127.0.0.1、VPC 内の IP、あるいは期限切れの ngrok トンネル——hiapi からは到達できません。
2. HTTPS / TLS の問題。 自己署名証明書、期限切れ証明書、中間証明書の欠落、またはホスト名の不一致。hiapi は https:// で始まる URL にのみ POST し、証明書チェーンを検証します。
3. ハンドラーがタイムアウト内に 2xx を返していない。 コールバックハンドラー内で同期的に時間のかかる処理（DB 書き込み、画像ダウンロード、通知送信）を行うと、200 を返す前にリクエストがタイムアウトします。hiapi 側から見ればこれは失敗です。
4. Webhook Sign Key を登録しておらず、ハンドラーが未署名リクエストを拒否している。 Settings で署名キーを生成していない場合、hiapi が配信するリクエストボディには署名ヘッダーが付きません——あなたが実装した検証ミドルウェアはそのリクエストを無効とみなして破棄します。
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 をテストする。 あなたのネットワーク外の任意のマシン（モバイル回線のスマホ、クラウドシェル、オンライン 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 を返し、その後非同期で処理する。 ハンドラー内部では：リクエストペイロードをキュー / データテーブルに書き込み、200 OK を返し、その後バックグラウンドワーカーで作業を処理します。レスポンスが遅い下流呼び出しでブロックされないようにしてください。
6. Webhook Sign Key を生成し、検証方法を統一する。 /en/dashboard/settings → Webhook Sign Key → Generate に進み、キーを保存します。ハンドラーが署名を検証する場合は保存したキーを使用し、検証しない場合は一時的に検証を無効にして配信が正常であることを確認してから再度有効にしてください。
7. /en/dashboard/logs を確認する。 呼び出しログにはリクエストとその終了状態が表示されます。呼び出しログの request_id を、サーバーが実際に受け取った内容（あれば）と比較することが、「コールバックが hiapi を離れたか」と「コールバックが自分のサーバーに届いたか」を特定する最速の方法です。

最小検証例

以下を使用して、API キー、タスク作成パス、コールバックエンドポイントをエンドツーエンドで確認します。スモークテストには高速な画像モデルを選びます。公開ドキュメントによると、モデル 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"}
  }'

tk-hiapi-... の形をした taskId を含む JSON レスポンスがすぐに返ってくるはずです。次に、タスクが success または fail になったら、サーバーログを監視して /hiapi/callback への受信 POST があるか確認します。タスク作成の段階で 401 Unauthorized が返る場合は、問題はキーにあります——hiapi のエラー封筒の仕組みについては hiapi が 429 を返す理由（および対処法） を参照してください（同じ 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} のポーリングをフォールバックとして併用することです。これにより、コールバック経路で一度障害が起きても結果を失いません。

コールバック URL は HTTPS ではなく HTTP を使用できますか？ いいえ。https:// で始まる URL のみ受け付けます。ローカルでテストする場合は、TLS を終端するトンネル（Cloudflare Tunnel、ngrok、tailscale funnel）を使用し、コールバックを公網の HTTPS エンドポイントに向けてください。

ハンドラーがリクエストボディを受け取ったのに署名検証が失敗するのはなぜですか？ 原因は (a) タスクを送信した後に Webhook Sign Key を生成した——リクエストは古いキー（またはキーなし）で署名されている——ので、再生成して保存し、新しいタスクを送信するか、(b) 検証コードの正規文字列の再構築方法が hiapi と異なるかのいずれかです。サーバーが受け取ったリクエストボディの正確なバイト列を記録し、その正確なバイト列に対して HMAC を再実行してください。途中で JSON の再シリアライズを一切行わないでください。

taskId は success を示しているのに、コールバックも結果 URL も受け取っていません。 GET /v1/tasks/{taskId} を再リクエストし、output 配列を確認してください。output[*].url の URL には時間制限（expireAt）があります。すぐにダウンロードしてください。コールバック配信と URL の有効期限は独立した問題です——コールバックがなくても、GET エンドポイントが信頼できる情報源です。

/en/dashboard/logs にコールバックが表示されるのに、サーバーが記録していません。 これは問題が hiapi ではなく、あなたの境界ネットワークにあることを示します。よくある原因：CDN / WAF ルールがチーム識別可能な User-Agent を持たない POST リクエストをブロックしている、ファイアウォールの IP 許可リスト、またはリバースプロキシがパスを書き換えている。ファイアウォールでその受信 POST を許可し、再実行してください。

コールバック URL はアカウントのレート制限を消費しますか？ いいえ。コールバックは hiapi からあなたへの配信であり、POST /v1/tasks のレート予算とは無関係です。