Tài liệu tham khảo API: Webhook

Webhook gửi đi thông báo cho các hệ thống của bạn khi có sự kiện xảy ra trong ProcessMind. Mỗi lần gửi là một yêu cầu JSON POST được ký bằng mã bí mật webhook của bạn: header X-ProcessMind-Signature chứa sha256=<hex>, giá trị HMAC-SHA256 của nội dung yêu cầu thô. Hãy xác minh chữ ký trên đúng các byte nhận được (trước khi phân tích JSON) và từ chối yêu cầu nếu chữ ký không khớp. Mỗi nội dung yêu cầu cũng có deliveryId để bạn loại bỏ các lần gửi trùng lặp, vì hệ thống có thể gửi lại.

Liệt kê webhook gửi đi

Endpoint: GET /v1/tenant/{tenantId}/webhooks

Xác thực: API key giới hạn theo tenant · phạm vi read

Tham số:

Tên	Kiểu	Vị trí	Bắt buộc	Mô tả
tenantId	string	path	Có	Định dạng: uuid
limit	integer	query	Không	Số mục tối đa cần trả về
offset	integer	query	Không	Số mục cần bỏ qua

Phản hồi (200):

Danh sách webhook

[
	{
		"id": "00000000-0000-0000-0000-000000000000",
		"url": "string",
		"events": [
			"process.created"
		],
		"description": "string",
		"isActive": true,
		"createdAt": "2024-03-15T16:30:00Z"
	}
]

Lỗi:

• 401 Thiếu, không hợp lệ, đã tắt hoặc hết hạn API key

Tạo webhook gửi đi (chỉ trả về mã bí mật dùng để ký một lần)

Endpoint: POST /v1/tenant/{tenantId}/webhooks

Xác thực: API key giới hạn theo tenant · phạm vi write

Tham số:

Tên	Kiểu	Vị trí	Bắt buộc	Mô tả
tenantId	string	path	Có	Định dạng: uuid

Nội dung yêu cầu:

{
	"url": "string",
	"events": [
		"process.created"
	],
	"description": "string"
}

Trường	Kiểu	Bắt buộc	Mô tả
url	string	Có	Endpoint https công khai nhận các yêu cầu POST có chữ ký (không dùng địa chỉ riêng tư hoặc địa chỉ loopback)
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Có	Các sự kiện kích hoạt việc gửi đến webhook này
description	string	Không	Mô tả tùy chọn Độ dài tối đa: 500

Phản hồi (201):

Đã tạo webhook (kèm mã bí mật dùng để ký)

{
	"id": "00000000-0000-0000-0000-000000000000",
	"url": "string",
	"events": [
		"process.created"
	],
	"description": "string",
	"isActive": true,
	"createdAt": "2024-03-15T16:30:00Z",
	"secret": "string"
}

Trường	Kiểu	Bắt buộc	Mô tả
id	string	Có	Định dạng: uuid
url	string	Có	Định dạng: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Có
description	string	Có	Độ dài tối đa: 500
isActive	boolean	Có	Mặc định: true
createdAt	string	Có	Định dạng: date-time
secret	string	Có	Mã bí mật dùng để ký; chỉ trả về tại đây khi tạo webhook

Lỗi:

• 400 Yêu cầu không hợp lệ: ví dụ, biểu thức bộ lọc sai, quy trình chưa có mô hình, loại tệp tải lên không được hỗ trợ hoặc thiếu trường bắt buộc
• 401 Thiếu, không hợp lệ, đã tắt hoặc hết hạn API key

Lấy thông tin một webhook gửi đi

Endpoint: GET /v1/tenant/{tenantId}/webhooks/{webhookId}

Xác thực: API key giới hạn theo tenant · read phạm vi

Tham số:

Tên	Kiểu	Vị trí	Bắt buộc	Mô tả
tenantId	string	path	Có	Định dạng: uuid
webhookId	string	path	Có	Định dạng: uuid

Phản hồi (200):

Webhook

{
	"id": "00000000-0000-0000-0000-000000000000",
	"url": "string",
	"events": [
		"process.created"
	],
	"description": "string",
	"isActive": true,
	"createdAt": "2024-03-15T16:30:00Z"
}

Trường	Kiểu	Bắt buộc	Mô tả
id	string	Có	Định dạng: uuid
url	string	Có	Định dạng: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Có
description	string	Có	Độ dài tối đa: 500
isActive	boolean	Có	Mặc định: true
createdAt	string	Có	Định dạng: date-time

Lỗi:

• 401 Thiếu, không hợp lệ, đã tắt hoặc hết hạn API key
• 404 Không tìm thấy tài nguyên

Cập nhật webhook gửi đi

Endpoint: PUT /v1/tenant/{tenantId}/webhooks/{webhookId}

Xác thực: API key giới hạn theo tenant · write phạm vi

Tham số:

Tên	Kiểu	Vị trí	Bắt buộc	Mô tả
tenantId	string	path	Có	Định dạng: uuid
webhookId	string	path	Có	Định dạng: uuid

Nội dung yêu cầu:

{
	"url": "string",
	"events": [
		"process.created"
	],
	"description": "string",
	"isActive": true
}

Trường	Kiểu	Bắt buộc	Mô tả
url	string	Không	Endpoint https công khai nhận các lần gửi POST có chữ ký
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Không	Các sự kiện kích hoạt việc gửi đến webhook này
description	string	Không	Mô tả không bắt buộc Độ dài tối đa: 500
isActive	boolean	Không	Webhook có được bật hay không

Phản hồi (200):

Webhook đã cập nhật

{
	"id": "00000000-0000-0000-0000-000000000000",
	"url": "string",
	"events": [
		"process.created"
	],
	"description": "string",
	"isActive": true,
	"createdAt": "2024-03-15T16:30:00Z"
}

Trường	Kiểu	Bắt buộc	Mô tả
id	string	Có	Định dạng: uuid
url	string	Có	Định dạng: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Có
description	string	Có	Độ dài tối đa: 500
isActive	boolean	Có	Mặc định: true
createdAt	string	Có	Định dạng: date-time

Lỗi:

• 401 Thiếu, không hợp lệ, đã tắt hoặc hết hạn API key
• 404 Không tìm thấy tài nguyên

Xóa webhook gửi đi

Endpoint: DELETE /v1/tenant/{tenantId}/webhooks/{webhookId}

Xác thực: API key giới hạn theo tenant · write phạm vi

Tham số:

Tên	Kiểu	Vị trí	Bắt buộc	Mô tả
tenantId	string	path	Có	Định dạng: uuid
webhookId	string	path	Có	Định dạng: uuid

Phản hồi (200):

Đã xóa webhook

{
	"deleted": true
}

Trường	Kiểu	Bắt buộc	Mô tả
deleted	boolean	Có

Lỗi:

• 401 Thiếu, không hợp lệ, đã tắt hoặc hết hạn API key
• 404 Không tìm thấy tài nguyên

Gửi thử một thông báo đến webhook

Endpoint: POST /v1/tenant/{tenantId}/webhooks/{webhookId}/test

Xác thực: API key giới hạn theo tenant · write phạm vi

Tham số:

Tên	Kiểu	Vị trí	Bắt buộc	Mô tả
tenantId	string	path	Có	Định dạng: uuid
webhookId	string	path	Có	Định dạng: uuid

Phản hồi (200):

Đã gửi thông báo thử

{
	"message": "string"
}

Trường	Kiểu	Bắt buộc	Mô tả
message	string	Có

Lỗi:

• 401 Thiếu, không hợp lệ, đã tắt hoặc hết hạn API key
• 404 Không tìm thấy tài nguyên