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.

Webhooks

Webhooks cho phép bạn nhận cập nhật theo thời gian thực từ Meshy khi các tác vụ API của bạn hoàn thành hoặc thay đổi trạng thái. Sau khi được cấu hình, Meshy sẽ POST payload sự kiện dưới định dạng json đến các URL mà bạn chỉ định.

Vì sao nên tạo Webhooks

Sử dụng webhooks mang lại nhiều lợi ích, đặc biệt là trong việc tự động kiểm tra trạng thái tác vụ API. Webhooks đòi hỏi ít công sức và chi phí hơn so với việc liên tục polling API để lấy cập nhật trạng thái tác vụ. Webhooks cũng cho phép cập nhật gần như theo thời gian thực và cuối cùng mở rộng quy mô tốt hơn so với polling API. Điều này cũng giúp bạn quản lý giới hạn tần suất (rate limit) tốt hơn, đặc biệt nếu bạn đang polling liên tục.

Thiết lập & Cấu hình

Để bật webhooks, mở trang Webhooks trong Developer Platform và nhấp vào nút "Create Webhook". Cung cấp URL https mà bạn muốn nhận webhooks và bật webhook để tự động nhận cập nhật tác vụ từ Meshy. Bạn có thể có tối đa 5 webhooks đang hoạt động cho mỗi tài khoản Meshy. Khi một webhook được bật, tất cả cập nhật trạng thái tác vụ API sẽ tự động được gửi đến URL payload. Vì mục đích bảo mật, hiện tại chúng tôi chỉ cho phép gửi webhooks đến các URL https. Nếu bạn muốn cấu hình kiểm thử cục bộ, hãy xem phần sau đây.

Yêu cầu Phân phối Webhook

Để webhook của bạn hoạt động bình thường và tiếp tục nhận sự kiện:

  • Máy chủ của bạn phải phản hồi với mã trạng thái HTTP dưới 400 (ví dụ: 200 OK, 202 Accepted).
  • Bất kỳ phản hồi nào có mã trạng thái >= 400 sẽ được coi là phân phối thất bại.
  • Nhiều lần thất bại liên tiếp có thể:
    • Khiến các cập nhật progress bị trì hoãn hoặc đến không đúng thứ tự
    • Tự động vô hiệu hóa webhook của bạn sau nhiều lần thử lại (xem Chính sách Tự động Vô hiệu hóa)

Mẹo: Luôn trả về phản hồi thành công sau khi bạn xác thực và lưu trữ payload webhook, ngay cả khi quá trình xử lý tiếp theo diễn ra bất đồng bộ.

Nếu sự kiện cuối cùng của một tác vụ chưa đến sau khoảng gấp đôi thời gian thông thường của nó, hãy lấy tác vụ bằng endpoint GET của nó. Xem Vòng đời Tác vụ để biết thời gian thông thường và thời gian cần chờ.

Chuyển tiếp Webhooks để Kiểm thử Cục bộ

Nếu bạn muốn kiểm thử mã webhook của mình ở local, mã này thường nằm ở địa chỉ http, bạn có thể sử dụng URL proxy webhook để chuyển tiếp webhooks đến máy tính hoặc codespace của mình. Dưới đây là các bước được đề xuất sử dụng smee.io, nhưng bạn có thể sử dụng bất kỳ dịch vụ nào bạn muốn để tạo URL proxy webhook.

Lấy URL proxy webhook:

  1. Trong trình duyệt của bạn, điều hướng đến https://smee.io/
  2. Nhấp vào "Start a new channel"
  3. Sao chép toàn bộ URL dưới mục "Webhook Proxy URL". Bạn sẽ sử dụng URL này trong các bước thiết lập tiếp theo.

Chuyển tiếp webhooks:

  1. Nếu bạn chưa cài đặt smee-client, hãy chạy lệnh sau trong terminal của bạn.
npm install --global smee-client
  1. Để nhận webhooks được chuyển tiếp từ smee.io, hãy chạy lệnh sau trong terminal của bạn. Thay thế WEBHOOK_PROXY_URL bằng URL proxy webhook của bạn từ trước đó.
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

Bạn sẽ thấy kết quả đầu ra trông như thế này, 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
  1. Giữ cho tiến trình này chạy trong khi bạn kiểm thử webhook của mình. Khi bạn muốn dừng việc chuyển tiếp webhooks, hãy nhấn Ctrl+C.
    Lưu ý rằng path là /webhook và port là 3000. Các giá trị này có thể hữu ích khi bạn muốn thiết lập mã của riêng mình để nhận các lần phân phối webhook sau này.

Tạo một webhook:

Bây giờ bạn có thể sử dụng URL proxy webhook để tạo một webhook mới trên trang Webhooks.

Phản hồi Mẫu

Khi trạng thái tác vụ thay đổi, Meshy sẽ POST một payload webhook đến URL đã cấu hình của bạn. Payload chứa đối tượng tác vụ ở định dạng JSON. Để biết mô tả đầy đủ về tất cả thuộc tính của đối tượng tác vụ và các ví dụ payload, hãy xem: