Webhooks

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

Webhooksを作成する理由

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

セットアップと構成

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

Webhook配信要件

Webhookが正常に機能し、イベントを受信し続けるためには：

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

ヒント： Webhookペイロードを検証して保存した後は、さらなる処理が非同期で行われる場合でも、常に成功応答を返してください。

ローカルテストのためのWebhooks転送

Webhookコードをローカルでテストしたい場合、通常はhttpアドレスで行われますが、WebhookプロキシURLを使用してWebhooksをコンピュータやコードスペースに転送することができます。以下はsmee.ioを使用した推奨手順ですが、任意のサービスを使用してWebhookプロキシURLを生成することができます。

WebhookプロキシURLを取得する：

  1. ブラウザでhttps://smee.io/に移動します
  2. 「新しいチャネルを開始」をクリックします
  3. 「Webhook Proxy URL」の下にある完全なURLをコピーします。このURLは、次のセットアップ手順で使用します。

Webhooksを転送する：

  1. smee-clientがまだインストールされていない場合は、ターミナルで以下のコマンドを実行します。
npm install --global smee-client
  1. smee.ioから転送されたWebhooksを受信するには、ターミナルで以下のコマンドを実行します。先ほどのWebhookプロキシURLでWEBHOOK_PROXY_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形式のタスクオブジェクトが含まれています。すべてのタスクオブジェクトのプロパティと例のペイロードの完全な説明については、以下を参照してください：