Webhooks

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

Webhooksを作成する理由

Webhooksの利用には、特にAPIタスクのステータスを自動的にチェックするという点で、いくつもの利点があります。Webhooksは、APIを継続的にポーリングしてタスクステータスの更新を取得する方法と比べて、必要な労力とコストが少なくて済みます。また、Webhooksはほぼリアルタイムでの更新を可能にし、最終的にはAPIポーリングよりも優れたスケーラビリティを実現します。これにより、特に常にポーリングを行っている場合、レート制限をより効果的に管理できるようにもなります。

セットアップと設定

Webhooksを有効にするには、Developer Platform内のWebhooksページを開き、「Create Webhook」ボタンをクリックしてください。Webhooksを受け取りたい任意のhttps URLを指定し、Meshyからタスクの更新を自動的に受信できるようにWebhookを有効化します。 Meshyアカウントごとに、有効化できるWebhookは最大5件までです。Webhookが有効になっている場合、すべてのAPIタスクステータスの更新は自動的にペイロードURLへ送信されます。セキュリティ上の理由から、現時点ではWebhookの送信先としてhttps URLのみをサポートしています。ローカルテストを設定したい場合は、以下のセクションを参照してください。

Webhook配信の要件

Webhookが正常に機能し、イベントを継続的に受信し続けるためには、以下が必要です。

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

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

ローカルテスト用にWebhookを転送する

通常はhttpアドレスで動作するWebhookのコードをローカルでテストしたい場合、WebhookプロキシURLを使用して、お使いのコンピューターやcodespaceにWebhookを転送できます。以下はsmee.ioを使用した推奨手順ですが、WebhookプロキシURLを生成できるものであれば、どのサービスを使用しても構いません。

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

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

Webhookを転送する：

  1. smee-clientをまだインストールしていない場合は、ターミナルで以下のコマンドを実行してください。
npm install --global smee-client
  1. smee.ioから転送されるWebhookを受信するには、ターミナルで以下のコマンドを実行してください。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のテストを行っている間は、これを実行したままにしておいてください。Webhookの転送を停止したい場合は、Ctrl+Cを入力してください。
    パスが/webhookで、ポートが3000であることに注意してください。これらの値は、後で独自のコードを設定してWebhookの配信を受信する際に役立ちます。

Webhookを作成する：

これで、WebhooksページでWebhookプロキシURLを使用し、新しいWebhookを作成できるようになります。

サンプルレスポンス

タスクのステータスが変化すると、Meshyは設定されたURLに対してWebhookのペイロードをPOSTします。このペイロードには、JSON形式のタスクオブジェクトが含まれます。すべてのタスクオブジェクトのプロパティおよびペイロードの例に関する詳細な説明については、以下を参照してください。