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 tất hoặc thay đổi trạng thái. Sau khi được cấu hình, Meshy sẽ POST các payload sự kiện ở định dạng json đến các URL bạn chỉ định.

Tại sao tạo Webhooks

Việc sử dụng webhooks có một số 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 thăm dò API để lấy các 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 có khả năng mở rộng tốt hơn so với thăm dò API. Điều này cũng giúp bạn quản lý giới hạn tốc độ tốt hơn, đặc biệt nếu bạn đang thăm dò liên tục.

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

Để bật webhooks, hãy điều hướng đến trang cài đặt API khi đã đăng nhập vào ứng dụng web Meshy. Tìm phần "Webhooks" bên dưới API key của bạn và nhấp vào nút "Tạo Webhook". Cung cấp URL https mong muốn của bạn để nhận webhooks và bật webhook để tự động nhận các 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ác cập nhật trạng thái tác vụ API sẽ tự động được gửi đến URL payload. Vì lý do 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ê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 bằng 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 tắt webhook của bạn sau các lần thử lặp lại (xem Chính sách tự động tắt)

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ộ.

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 cục bộ, thường là tại một đị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 bạn. Dưới đây là các bước được đề xuất khi 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 "Bắt đầu một kênh mới"
  3. Sao chép URL đầy đủ bên dưới "URL proxy webhook". Bạn sẽ sử dụng URL này trong các bước thiết lập sau.

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 đầ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ữ tiến trình này chạy trong khi bạn thử nghiệm webhook của mình. Khi bạn muốn dừng chuyển tiếp webhooks, hãy nhập 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 sau này 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.

Tạo webhook:

Bây giờ bạn có thể sử dụng URL proxy webhook để tạo webhook mới trong trang cài đặt Meshy API.

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