Webhooks
APIタスクがprogressを進めたり完了したりしたときに、MeshyがあなたのサーバーにPOSTリクエストを送るようにして、ポーリングの必要をなくせます。
Webhooksを使う理由
Webhooksは、各タスクのステータスをAPIにポーリングするよりも手間が少なく、コストも低く済みます。Meshyは更新が発生するたびに送信するため、より早く情報を受け取れますし、Webhooksはポーリングよりもスケールします。送信するリクエストの数も減るため、レート制限からより余裕を持てます。
Webhookを設定する
Webhookを追加するには、以下の手順に従ってください。
- Developer PlatformのWebhooksページを開き、Create Webhookをクリックします。
- Payload URLに、配信を受け取るURLを入力します。Meshyは
https://経由でのみ配信します。 - ダイアログが入力するWebhook Secretのコピーを保管してください。すべての配信にこれが付与されるため、サーバー側でリクエストがMeshyから来たものかを確認できます。既存のWebhookについては、Secret列の目のアイコンをクリックすると確認できます。
- Activeを選択し、Confirmをクリックします。
各アカウントは、アクティブなWebhookを5件、合計で10件まで保持できます。アクティブなWebhookはすべて、あなたのすべてのAPIタスクのステータス更新を受け取ります。
自分のコンピューター上のサーバーでWebhookをテストする方法については、自分のコンピューターでテストするを参照してください。
配信を処理する
配信を受け付けるには、200や202など、400未満のステータスで応答してください。Meshyは応答を約25秒待つため、先に配信内容を保存してから応答してください。モデルのダウンロードなどの時間のかかる処理は、その後に行ってください。
400以上のステータス、または応答がない場合は、配信失敗として扱われます。Meshyは試行間隔を徐々に広げながら再試行し、IN_PROGRESSの更新では最大4回、最終ステータスでは最大9回まで再試行します。連続する20件の更新がすべての試行で失敗すると、Meshyはそのwebhookを無効化することがあります。再度有効にするには、Webhooksページでそのwebhookを編集し、Activeを選択してください。
以下のようなケースに対応できるコードを書いてください。
- 配信は順序どおりに届かないことがあります。
IN_PROGRESSの配信が最終配信の後に届くことがあるため、それによって最終ステータスを上書きしないようにしてください。 - 同じ更新が複数回届くことがあります。
idとstatusの組み合わせごとに一度だけ処理してください。 - あなたのURLを知っている人なら誰でもリクエストを送信できます。
X-MESHY-API-WEBHOOK-SECRET-KEYを手元のシークレットのコピーと比較し、一致しないリクエストは拒否してください。
タスクの最終配信が、そのタスクの典型的な所要時間のおよそ2倍経っても届かない場合は、そのタスクのGETエンドポイントから取得してください。典型的な所要時間とどのくらい待つべきかについては、タスクのライフサイクルを参照してください。
自分のコンピューターでテストする
Meshyは公開されたhttps://のURLにのみ配信するため、あなたのコンピューター上のサーバーに直接届けることはできません。あなたのコンピューター上のコードをテストするには、webhookプロキシを使って公開URLをそこに転送してください。以下の手順ではsmee.ioを使用しますが、どのwebhookプロキシサービスでも同様に動作します。
-
smee.ioを開き、Start a new channelをクリックします。Webhook Proxy URLの下にあるURLをコピーしてください。
-
smeeクライアントをまだお持ちでない場合は、インストールしてください。
npm install --global smee-client -
チャンネルをあなたのサーバーに転送します。
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テスト中はこれを実行したままにしてください。転送を止めるには、Ctrl+Cを押します。あなたのサーバーはポート
3000のパス/webhookで配信を受け取るため、そこでリッスンするようにコードを設定してください。 -
Webhooksページで、WebhookプロキシURLをPayload URLとしたWebhookを作成してください。
配信ペイロード
Meshyは、タスクがIN_PROGRESSの間に1件配信を送り、タスクが最終ステータスに達したときにもう1件送ります。タスクがIN_PROGRESSの配信を経ずに最終ステータスに達することもあります。
各配信は、以下のヘッダーを伴ったPayload URLへのPOSTです。
| Header | Value |
|---|---|
X-MESHY-API-WEBHOOK-SECRET-KEY | webhookのシークレット |
X-MESHY-API-WEBHOOK-USER-ID | webhookを所有するMeshyユーザーのID |
Meshy-Webhook-Version | v1(ボディの形式) |
Content-Type | application/json |
User-Agent | MeshyAPIWebhook/1.0.0 |
JSONボディはタスクオブジェクトです。これは、そのタスクのGETエンドポイントが返すものと同じオブジェクトですが、progressだけは異なります。配信におけるprogressは、以下のいずれかの値で送られます。
- タスクが
IN_PROGRESSの間は50 - タスクが成功したときは
100 - タスクが失敗またはキャンセルされたときは
0
各タスクオブジェクトのフィールドと例については、以下のセクションを参照してください。