Webhooks

Webhooksを使用すると、APIタスクが完了したりステータスが変更されたりした際に、Meshyからリアルタイムの更新を受け取ることができます。設定が完了すると、Meshyはイベントペイロードをjson形式で、指定したURLにPOSTします。

Webhooksを作成する理由

webhooksを使用することには、特にAPIタスクのステータスを自動的に確認するうえで、いくつかの利点があります。Webhooksは、タスクステータスの更新を取得するためにAPIを継続的にポーリングするよりも、手間とコストが少なくて済みます。また、Webhooksはほぼリアルタイムの更新を可能にし、最終的にはAPIポーリングよりもスケールしやすくなります。これにより、特に継続的にポーリングしている場合に、レート制限をより適切に管理することもできます。

セットアップと設定

webhooksを有効にするには、Meshy Webアプリケーションにログインした状態でAPI設定ページに移動します。API keyの下にある「Webhooks」セクションを見つけ、「Create Webhook」ボタンをクリックします。Meshyからwebhooksを受け取るための任意のhttps URLを入力し、webhookを有効にすると、Meshyからタスク更新を自動的に受信できます。 Meshyアカウントごとに最大5つのアクティブなwebhooksを持つことができます。webhookが有効になっている場合、すべてのAPIタスクステータス更新がペイロードURLに自動的に送信されます。セキュリティ上の理由により、現時点ではhttps URLへのwebhooks送信のみを許可しています。ローカルテストを設定したい場合は、次のセクションを参照してください。

Webhook配信要件

Webhookが正常に機能し、イベントの受信を継続するには、次の要件を満たす必要があります。

  • サーバーは400未満のHTTPステータスコード（例：200 OK、202 Accepted）で応答する必要があります。
  • ステータスコードが>= 400のレスポンスは、配信失敗として扱われます。
  • 連続して複数回失敗すると、次のことが発生する可能性があります。
    • 進行状況の更新が遅延したり、順序が前後して到着したりする
    • 繰り返し試行された後、webhookが自動的に無効化される（自動無効化ポリシーを参照）

ヒント： webhookペイロードを検証して保存した後は、その後の処理が非同期で行われる場合でも、必ず成功レスポンスを返してください。

ローカルテスト用のWebhooks転送

通常httpアドレスであるローカル環境でwebhookコードをテストしたい場合は、webhookプロキシURLを使用して、webhooksをコンピューターまたはcodespaceに転送できます。以下はsmee.ioを使用する推奨手順ですが、webhookプロキシURLを生成できる任意のサービスを使用できます。

webhookプロキシURLを取得する:

  1. ブラウザで https://smee.io/ に移動します
  2. 「Start a new channel」をクリックします
  3. 「Webhook Proxy URL」の下にある完全なURLをコピーします。このURLは、以降のセットアップ手順で使用します。

webhooksを転送する:

  1. まだsmee-clientをインストールしていない場合は、ターミナルで次のコマンドを実行します。
npm install --global smee-client
  1. smee.ioから転送されたwebhooksを受信するには、ターミナルで次のコマンドを実行します。WEBHOOK_PROXY_URLを、先ほど取得したwebhookプロキシURLに置き換えてください。
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

次のような出力が表示されます。ここでWEBHOOK_PROXY_URLはあなたのwebhookプロキシURLです。

Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL
  1. webhookをテストしている間は、このプロセスを実行したままにしてください。webhooksの転送を停止したい場合は、Ctrl+Cを入力します。
    パスは/webhook、ポートは3000であることに注意してください。これらの値は、後でwebhook配信を受信するための独自コードを設定する際に役立つ場合があります。

webhookを作成する:

これで、webhookプロキシURLを使用して、Meshy API設定ページで新しいwebhookを作成できます。

レスポンス例

タスクステータスが変更されると、Meshyは設定済みURLにwebhookペイロードをPOSTします。ペイロードには、JSON形式のタスクオブジェクトが含まれます。すべてのタスクオブジェクトプロパティとペイロード例の完全な説明については、以下を参照してください。