Webhooks

Webhooks cho phép bạn nhận các 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 bạn chỉ định.

Why Create Webhooks

Sử dụng webhook 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. Webhook đò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ụ. Webhook cũng cho phép cập nhật gần như theo thời gian thực và cuối cùng có khả năng mở rộng 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ốc độ (rate limit) tốt hơn, đặc biệt nếu bạn đang polling liên tục.

Setup & Configuration

Để bật webhook, mở trang Webhooks trong Developer Platform và nhấp vào nút "Create Webhook". Cung cấp URL https mong muốn để nhận webhook 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 webhook đang hoạt động cho mỗi tài khoản Meshy. Khi một webhook được bật, tất cả các cập nhật trạng thái tác vụ API sẽ được tự động 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 webhook đến các URL https. Nếu bạn muốn cấu hình kiểm thử cục bộ (local testing), hãy xem phần tiếp theo.

Webhook Delivery Requirements

Để 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à gử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 theo đúng thứ tự
    • Tự động vô hiệu hóa webhook của bạn sau nhiều lần thử liên tiếp (xem Auto-Disable Policy)

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 việc xử lý tiếp theo diễn ra bất đồng bộ.

Forwarding Webhooks for Local Testing

Nếu bạn muốn kiểm thử mã webhook của mình cục bộ, thường là ở một địa chỉ http, bạn có thể sử dụng URL proxy webhook để chuyển tiếp webhook đến máy tính hoặc codespace của bạn. Dưới đây là các bước được khuyến nghị 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.

Get a webhook proxy URL:

  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 URL đầy đủ 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.

Forward 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 webhook đượ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 giố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
  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 webhook, nhấn Ctrl+C.
    Lưu ý rằng đường dẫn là /webhook và cổng 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 gửi webhook sau này.

Create a webhook:

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

Sample Response

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ả các thuộc tính của đối tượng tác vụ và các ví dụ payload, hãy xem: