Kích hoạt bằng Webhook

Webhook là một địa chỉ riêng của workflow. Khi một hệ thống khác (phần mềm nội bộ, form, công cụ tự động hoá…) gửi yêu cầu tới địa chỉ này, workflow sẽ chạy với dữ liệu được gửi kèm.

Mở phần cài đặt webhookSao chép liên kết

1. Mở workflow.
2. Bấm nút Lịch chạy & Webhook, nằm cạnh công tắc bật/tắt workflow.
3. Chọn thẻ Webhook.

Ai được thay đổi webhook? Chủ sở hữu workflow và người có quyền chỉnh sửa. Người chỉ có quyền xem thì chỉ xem được.

Tạo webhookSao chép liên kết

1. Bấm Tạo webhook.
2. Hộp thoại hiện Địa chỉ webhook (URL) và Mã bí mật (Bearer token).
3. Sao chép mã bí mật ngay và lưu ở nơi an toàn.

Sau đó, thẻ Webhook chỉ hiện vài ký tự cuối của mã, kèm lần gọi gần nhất, số lần gọi và một lệnh curl mẫu.

Quản lý webhookSao chép liên kết

• Tạo mã mới: cấp mã bí mật mới. Mã cũ ngừng hoạt động ngay, nên hãy cập nhật mã mới vào hệ thống đang gọi.
• Công tắc: tạm tắt hoặc bật lại webhook.
• Xoá: xoá webhook.

Gọi webhookSao chép liên kết

Gửi yêu cầu POST tới địa chỉ webhook với hai header:

• Authorization: Bearer <mã bí mật>
• Content-Type: application/json

Phần thân là một đối tượng JSON. Mỗi khoá ở cấp ngoài cùng là một trường đầu vào của workflow. Thẻ Webhook có liệt kê các trường đầu vào của workflow. Dung lượng phần thân tối đa 256 KB.

Các ví dụ dưới đây dùng địa chỉ và mã giả. Hãy thay bằng địa chỉ và mã của bạn.

curl -X POST 'https://<địa-chỉ-api>/api/v1/hooks/workflows/wh_xxx?wait=30' \
  -H 'Authorization: Bearer whk_xxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: don-hang-1024' \
  -d '{"topic": "Tin tức ngân hàng", "max_items": 5}'

import requests

resp = requests.post(
    "https://<địa-chỉ-api>/api/v1/hooks/workflows/wh_xxx",
    params={"wait": 30},
    headers={
        "Authorization": "Bearer whk_xxx",
        "Idempotency-Key": "don-hang-1024",
    },
    json={"topic": "Tin tức ngân hàng", "max_items": 5},
    timeout=90,
)
print(resp.status_code, resp.json())

Kết quả trả vềSao chép liên kết

• Mặc định, webhook trả về ngay mã 202 kèm run_id (mã lần chạy), status (trạng thái) và status_url (địa chỉ để theo dõi).
• Muốn chờ kết quả, thêm ?wait= với số giây từ 1 đến 60. Nếu workflow chạy xong trong thời gian đó, bạn nhận được luôn outputs (kết quả). Nếu chưa xong, bạn vẫn nhận 202 như mặc định.
• Theo dõi lần chạy: gọi GET tới status_url với cùng mã bí mật để lấy trạng thái và kết quả.

Tránh chạy trùng: Idempotency-KeySao chép liên kết

Nếu hệ thống của bạn có thể gửi lại cùng một yêu cầu (ví dụ khi mạng chập chờn), hãy thêm header Idempotency-Key với một giá trị riêng cho mỗi yêu cầu. Gửi lại cùng giá trị trong vòng 24 giờ sẽ nhận về lần chạy ban đầu, thay vì tạo một lần chạy mới.

Giới hạn và mã lỗiSao chép liên kết

• Tối đa 30 lần gọi mỗi phút cho mỗi webhook.
• Tối đa 3 lần chạy cùng lúc cho mỗi webhook.

Webhook chạy với quyền của ai?Sao chép liên kết

Các lần chạy qua webhook dùng quyền của người đã tạo webhook, hoặc người tạo mã mới gần nhất.

Xem các lần chạy qua webhookSao chép liên kết

Trong Lịch sử chạy, các lần chạy qua webhook được ghi là Webhook.

Xem thêmSao chép liên kết

• Lên lịch chạy tự động: chạy workflow theo giờ cố định, không cần hệ thống khác gọi.