@digiforce-nc/plugin-workflow-webhook

Plugin đăng ký trigger kích hoạt workflow từ webhook URL, mở rộng plugin-workflow. Hệ thống bên ngoài gửi HTTP request đến URL webhook unique, workflow tự động khởi chạy với dữ liệu từ request body.

Plugin này làm gì?

Webhook Trigger tạo một URL endpoint duy nhất cho mỗi workflow. Khi hệ thống bên ngoài (CRM, payment gateway, CI/CD, ...) gửi HTTP POST đến URL này, workflow được kích hoạt với toàn bộ dữ liệu từ request body làm input.

Webhook URL có dạng: https://your-domain.com/api/webhooks/:webhookId

Mỗi workflow có một webhookId unique, đảm bảo chỉ workflow đúng được kích hoạt. Secret token bảo vệ endpoint khỏi request trái phép.

Cấu hình

Tham số	Kiểu	Mô tả
`enabled`	`boolean`	Bật/tắt webhook endpoint
`secret`	`string`	Secret token xác thực request (header Authorization)
`sync`	`boolean`	`true`: chờ workflow xong rồi trả result; `false`: trả 202 ngay
`method`	`string`	HTTP method chấp nhận (mặc định: POST)

Input / Output

Hướng	Dữ liệu	Mô tả
Input	`body`	Request body (JSON) từ hệ thống bên ngoài
Input	`headers`	HTTP headers của request
Input	`query`	Query parameters
Output	`status`	HTTP status code trả về
Output	`body`	Response body (khi sync mode)

Tính năng chính

#	Tính năng	Chi tiết
1	URL unique	Mỗi workflow có URL webhook riêng, dễ quản lý
2	Secret token	Bảo mật endpoint bằng token xác thực
3	Sync / Async	Chọn trả kết quả ngay hoặc chạy nền
4	JSON parsing	Tự động parse request body thành object
5	Retry-safe	Idempotent - an toàn khi hệ thống ngoài retry

Trường hợp sử dụng

#	Kịch bản	Mô tả
1	Payment callback	Cổng thanh toán gọi webhook khi giao dịch hoàn tất
2	GitHub webhook	Nhận event push/PR từ GitHub, tự động cập nhật task
3	IoT data ingestion	Thiết bị IoT gửi dữ liệu sensor qua webhook
4	Zapier / n8n	Kết nối với các nền tảng automation bên ngoài
5	Form submission	Nhận dữ liệu form từ landing page bên ngoài

Lưu ý quan trọng

Luôn bật secret để bảo vệ webhook khỏi request trái phép
Chế độ sync giữ connection mở - cẩn thận timeout nếu workflow chạy lâu
Webhook URL không thay đổi khi sửa workflow - an toàn cho hệ thống bên ngoài
Request body quá lớn (trên 1MB) có thể bị từ chối tùy cấu hình server
Test webhook bằng curl hoặc Postman trước khi cấu hình hệ thống bên ngoài

Dependencies

Package	Vai trò
`@digiforce-nc/plugin-workflow`	Workflow engine (peer)
`@digiforce-nc/server`	Server framework - route registration (peer)
`@digiforce-nc/actions`	Action context types (peer)