lowpoly sẽ ngừng hoạt động vào 30 thg 10, 2026. Hãy chuyển sang mô hình khác trước các ngày này để tránh lỗi yêu cầu. Xem tất cả mục ngừng hỗ trợ

Webhooks

Yêu cầu Meshy gửi một request POST đến server của bạn khi một tác vụ API có tiến triển hoặc hoàn tất, để bạn không cần phải polling.

Tại sao nên dùng webhooks

Webhooks tốn ít công sức hơn và chi phí thấp hơn so với việc polling API để lấy trạng thái của từng tác vụ. Meshy gửi từng cập nhật ngay khi nó xảy ra, nên bạn nhận được sớm hơn, và webhooks mở rộng quy mô tốt hơn so với polling. Bạn cũng gửi ít request hơn, giúp bạn tránh xa hơn giới hạn tốc độ của mình.

Thiết lập webhook

Để thêm một webhook, hãy làm theo các bước sau:

  1. Mở trang Webhooks trong Developer Platform, rồi nhấp vào Create Webhook.
  2. Tại Payload URL, nhập URL sẽ nhận các lượt gửi. Meshy chỉ gửi qua https://.
  3. Giữ lại một bản sao của Webhook Secret mà hộp thoại điền sẵn. Mỗi lượt gửi đều mang theo nó, để server của bạn có thể kiểm tra xem request có đến từ Meshy hay không. Đối với một webhook bạn đã có, hãy nhấp vào biểu tượng con mắt trong cột Secret của nó để xem.
  4. Chọn Active, rồi nhấp vào Confirm.

Mỗi tài khoản có thể có 5 webhooks đang hoạt động, và tối đa 10 webhooks tổng cộng. Mỗi webhook đang hoạt động đều nhận các cập nhật trạng thái của tất cả các tác vụ API của bạn.

Để kiểm tra một webhook với một server trên máy tính của bạn, xem Kiểm tra trên máy tính của bạn.

Xử lý một lượt gửi

Để chấp nhận một lượt gửi, hãy phản hồi với một mã trạng thái dưới 400, chẳng hạn như 200 hoặc 202. Meshy đợi khoảng 25 giây để nhận phản hồi, vì vậy hãy lưu lại lượt gửi và phản hồi trước. Thực hiện các công việc tốn thời gian sau đó, chẳng hạn như tải mô hình xuống.

Một mã trạng thái từ 400 trở lên, hoặc không có phản hồi, được tính là một lượt gửi thất bại. Meshy sẽ thử gửi lại với thời gian chờ giữa các lần thử dài hơn, tối đa 4 lần đối với một cập nhật IN_PROGRESS và tối đa 9 lần đối với trạng thái cuối cùng. Nếu 20 lượt cập nhật liên tiếp đều thất bại ở mọi lần thử, Meshy có thể vô hiệu hóa webhook. Để bật lại, hãy chỉnh sửa nó trên trang Webhooks và chọn Active.

Hãy viết mã của bạn để xử lý các trường hợp sau:

  • Các lượt gửi có thể đến không theo đúng thứ tự. Một lượt gửi IN_PROGRESS có thể đến sau lượt gửi cuối cùng, vì vậy đừng để nó thay thế trạng thái cuối cùng.
  • Cùng một cập nhật có thể đến nhiều hơn một lần. Hãy xử lý mỗi cặp id và status chỉ một lần.
  • Bất kỳ ai biết URL của bạn đều có thể gửi request đến đó. Hãy so sánh X-MESHY-API-WEBHOOK-SECRET-KEY với bản sao secret của bạn, và từ chối request nào không khớp.

Nếu lượt gửi cuối cùng của một tác vụ chưa đến sau khoảng gấp đôi thời gian xử lý thông thường của tác vụ đó, hãy lấy thông tin tác vụ từ endpoint GET của nó. Để biết thời gian xử lý thông thường và thời gian nên chờ, xem Vòng đời tác vụ.

Kiểm tra trên máy tính của bạn

Meshy chỉ gửi đến một URL https:// công khai, vì vậy nó không thể kết nối trực tiếp đến một server trên máy tính của bạn. Để kiểm tra mã trên máy tính của bạn, hãy chuyển tiếp một URL công khai đến nó bằng một webhook proxy. Các bước sau sử dụng smee.io, và bất kỳ dịch vụ webhook proxy nào cũng hoạt động theo cách tương tự.

  1. Mở smee.io và nhấp vào Start a new channel. Sao chép URL dưới Webhook Proxy URL.

  2. Nếu bạn chưa có smee client, hãy cài đặt nó:

    npm install --global smee-client

  3. Chuyển tiếp channel đến server của bạn. Thay thế WEBHOOK_PROXY_URL bằng URL proxy webhook của bạn:

    smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

    Kết quả đầu ra trông như sau, trong đó WEBHOOK_PROXY_URL là URL proxy webhook của bạn:

    Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL

    Giữ cho nó chạy trong khi bạn kiểm tra. Để dừng việc chuyển tiếp, nhấn Ctrl+C. Server của bạn nhận các lượt gửi trên cổng 3000 tại đường dẫn /webhook, vì vậy hãy thiết lập mã của bạn để lắng nghe tại đó.

  4. Trên trang Webhooks, tạo một webhook với URL proxy webhook làm Payload URL của nó.

Payload của lượt gửi

Meshy gửi một lượt gửi khi một tác vụ đang ở trạng thái IN_PROGRESS, và một lượt khác khi tác vụ đạt đến trạng thái cuối cùng. Một tác vụ có thể đạt đến trạng thái cuối cùng mà không có lượt gửi IN_PROGRESS nào.

Mỗi lượt gửi là một request POST đến URL payload của bạn với các header sau:

HeaderGiá trị
X-MESHY-API-WEBHOOK-SECRET-KEYSecret của webhook
X-MESHY-API-WEBHOOK-USER-IDID của người dùng Meshy sở hữu webhook
Meshy-Webhook-Versionv1, định dạng của phần thân
Content-Typeapplication/json
User-AgentMeshyAPIWebhook/1.0.0

Phần thân JSON là đối tượng tác vụ. Đó là cùng một đối tượng mà endpoint GET của tác vụ trả về, ngoại trừ progress. Một lượt gửi gửi progress dưới dạng một trong các giá trị sau:

  • 50 khi tác vụ đang ở trạng thái IN_PROGRESS
  • 100 khi tác vụ thành công
  • 0 khi tác vụ thất bại hoặc bị hủy

Để biết các trường của mỗi đối tượng tác vụ, cùng với ví dụ, xem các phần sau: