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 được hoàn thành 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

Sử dụng webhooks có nhiều lợi thế, đặc biệt là trong việc kiểm tra trạng thái tác vụ API một cách tự động. Webhooks yêu cầu ít nỗ lực và chi phí hơn so với việc liên tục thăm dò API để nhận 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 mở rộng tốt hơn so với thăm dò API. Điều này cũng cho phép bạn quản lý tốt hơn giới hạn tốc độ của mình, đặc biệt nếu bạn đang thăm dò liên tục.

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

Để kích hoạt webhooks, đ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 Keys 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à kích hoạ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 hoạt động cho mỗi tài khoản Meshy. Khi một webhook được kích hoạ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ì lý do bảo mật, chúng tôi chỉ cho phép gửi webhooks đến các URL https vào thời điểm này. Nếu bạn muốn cấu hình kiểm tra cục bộ, hãy xem phần sau.

Yêu cầu Giao hàng 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ột mã trạng thái HTTP dưới 400 (ví dụ: 200 OK, 202 Accepted).
  • Bất kỳ phản hồi nào với mã trạng thái >= 400 sẽ được coi là giao hàng thất bại.
  • Nhiều lần thất bại liên tiếp có thể:
    • Gây ra 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ử (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 xử lý thêm diễn ra không đồng bộ.

Chuyển tiếp Webhooks để kiểm tra cục bộ

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

Nhận một 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 "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, chạy lệnh sau trong terminal của bạn.
npm install --global smee-client
  1. Để nhận các webhooks được chuyển tiếp từ smee.io, 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, nơi 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ữ điều này chạy trong khi bạn kiểm tra webhook của mình. Khi bạn muốn dừng chuyển tiếp webhooks, 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 bạn muốn thiết lập mã của riêng mình để nhận giao hàng 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 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 bạn đã cấu hình. Payload chứa đối tượng tác vụ ở định dạng JSON. Để có mô tả đầy đủ về tất cả các thuộc tính đối tượng tác vụ và các payload mẫu, xem: