Webhook Endpoint
Vô hiệu hoá điểm cuối Webhook
Đặt trạng thái điểm cuối Webhook thành inactive mà không xoá điểm cuối.
https://api.unifyport.ai/v1/webhook-endpoints/{endpoint_id}/deactivateKênh được hỗ trợ
Trước khi gọi
Dùng X-Api-Key của workspace sở hữu tài nguyên trên máy chủ. Thay mọi giá trị mẫu trước khi chạy.
Nguồn tham số
- account_id
- Lấy data.id từ phản hồi tạo hoặc truy vấn tài khoản. ID thuộc workspace của X-Api-Key. Lấy tài khoản
Tham số yêu cầu
Tiêu đề
X-Api-KeyAPI key của không gian làm việc. Không gian làm việc được xác định từ tiêu đề này.
Tham số đường dẫn
endpoint_idĐịnh danh dùng cho route webhook endpoints.
Tham số truy vấn
account_idID tài khoản công khai tùy chọn, ví dụ acc_example. Không được rỗng, chỉ chứa khoảng trắng hoặc lặp lại. Tên tham số phải đúng là account_id; biến thể chữ hoa/chữ thường trả về 400 invalid_request, không được coi là bỏ qua. Khi liệt kê, bỏ qua thì chỉ trả về endpoint của không gian làm việc; chỉ định thì chỉ trả về cấu hình độc lập của tài khoản (data=[] nếu không có, không kèm cấu hình kế thừa từ không gian làm việc). Lấy chi tiết, vô hiệu hóa và xóa chỉ kiểm tra tài khoản sở hữu hiện có; không khớp trả về 400 invalid_request. Tài khoản được chỉ định không tồn tại hoặc không thuộc không gian làm việc hiện tại trả về 404 account_not_found (20020).
minLength: 1 · pattern: \S
Nội dung yêu cầu
Điểm cuối này không cần nội dung JSON.
Hiểu kết quả
Xác nhận status=inactive trong phản hồi. Không chờ giao sự kiện mới qua điểm nhận này; việc vô hiệu hóa không bảo đảm hủy yêu cầu đang được gửi.
Phản hồi 200 OK
{
"request_id": "<REQUEST_ID>",
"data": {
"id": "we_example",
"url": "https://example.com/webhook-updated",
"status": "inactive",
"subscribed_events": [
"message.delivered",
"message.read"
],
"signing_enabled": false,
"retry_policy": {
"max_attempts": 1
}
}
}
Nội dung phản hồi
idĐịnh danh điểm cuối webhook (we_...).
account_idID tài khoản công khai của endpoint độc lập của tài khoản; được bỏ qua với endpoint của không gian làm việc, không trả về null.
minLength: 1
urlURL HTTP(S) tuyệt đối nhận webhook; production nên dùng HTTPS.
format: uri
statusTrạng thái điểm cuối: active hoặc inactive.
enum: active, inactive
subscribed_events[]Public standard event của điểm cuối; ["*"] nghĩa là các public event mà không gian làm việc có quyền nhận, không gồm provider.raw_event.
signing_enabledtrue khi đã đặt secret ký và các lượt gửi được ký.
retry_policyobjectmax_attempts đếm retry sau lần gửi đầu, mặc định 3, phạm vi 0–5.
retry_policymax_attempts đếm retry sau lần gửi đầu, mặc định 3, phạm vi 0–5.
max_attemptsSố lần retry đã cấu hình sau lần gửi đầu, từ 0 đến 5.
Phản hồi
200200 OK
Yêu cầu thành công. Xem ví dụ nội dung phản hồi.
400Bad Request
Body, đường dẫn hoặc tham số yêu cầu không hợp lệ.
401Unauthorized
Header X-Api-Key thiếu hoặc không hợp lệ.
403Forbidden
Yêu cầu đã được nhận diện nhưng thao tác không được phép.
404Not Found
Không tìm thấy tài nguyên được yêu cầu. Kiểm tra error.code cùng với thao tác hiện tại.
500Internal Server Error
Dịch vụ gặp lỗi không mong muốn.
Khi yêu cầu thất bại
Kiểm tra HTTP và error.code/numeric_code, giữ request_id. Sửa tham số, tiếp tục xác thực hoặc kiểm tra runtime tùy nguyên nhân. Xác nhận kết quả cũ trước khi thử lại thao tác gửi hoặc ghi. Tham chiếu mã lỗi
Đọc trạng thái HTTP, error.code và error.numeric_code theo thao tác đang gọi. Mã số có kiểu chuỗi. Giữ request_id để chẩn đoán; đây không phải khóa chống lặp hay mã tác vụ.
- invalid_request · 10000 · 400
Kiểm tra JSON và các trường bắt buộc.
Xử lý và thử lại: Sửa tham số theo thao tác và điều kiện của kênh rồi mới gọi lại. Lặp lại yêu cầu sai y nguyên không khắc phục lỗi.
JSON minh họa; message thay đổi theo nguyên nhân thực tế · 400 · 10000
{ "request_id": "req_example", "error": { "code": "invalid_request", "numeric_code": "10000", "message": "Invalid request parameters" } }- invalid_target_workspace · 11003 · 400
Đích ghi đè workspace trống hoặc sai định dạng. Bỏ tiêu đề ghi đè và dùng API Key thuộc workspace đích.
Điều kiện: Áp dụng khi yêu cầu có tiêu đề X-Workspace-Id để ghi đè workspace.
Xử lý và thử lại: Sửa tham số theo thao tác và điều kiện của kênh rồi mới gọi lại. Lặp lại yêu cầu sai y nguyên không khắc phục lỗi.
JSON minh họa; message thay đổi theo nguyên nhân thực tế · 400 · 11003
{ "request_id": "req_example", "error": { "code": "invalid_target_workspace", "numeric_code": "11003", "message": "Invalid target workspace" } }- invalid_api_key · 11001 · 401
Kiểm tra API Key có đúng và được bật hay không.
Xử lý và thử lại: Giữ request_id và mã lỗi có cấu trúc; kiểm tra thao tác hiện tại trước khi chọn hành động tiếp theo.
JSON minh họa; message thay đổi theo nguyên nhân thực tế · 401 · 11001
{ "request_id": "req_example", "error": { "code": "invalid_api_key", "numeric_code": "11001", "message": "Invalid API key" } }- missing_api_key · 11000 · 401
Thêm tiêu đề X-Api-Key.
Xử lý và thử lại: Giữ request_id và mã lỗi có cấu trúc; kiểm tra thao tác hiện tại trước khi chọn hành động tiếp theo.
Ví dụ · 401 · 11000
{ "request_id": "req_xxx", "error": { "code": "missing_api_key", "numeric_code": "11000", "message": "Missing X-Api-Key header" } }- workspace_override_forbidden · 11002 · 403
Yêu cầu cố ghi đè workspace mà API Key không được phép dùng. Bỏ tiêu đề ghi đè và dùng API Key thuộc workspace đích.
Điều kiện: Áp dụng khi yêu cầu có tiêu đề X-Workspace-Id để ghi đè workspace.
Xử lý và thử lại: Giữ request_id và mã lỗi có cấu trúc; kiểm tra thao tác hiện tại trước khi chọn hành động tiếp theo.
JSON minh họa; message thay đổi theo nguyên nhân thực tế · 403 · 11002
{ "request_id": "req_example", "error": { "code": "workspace_override_forbidden", "numeric_code": "11002", "message": "Workspace override is not allowed" } }- account_not_found · 20020 · 404
Kiểm tra account_id và dùng X-Api-Key của không gian làm việc sở hữu tài khoản. Khóa hiện tại không truy cập được tài khoản không tìm thấy trong không gian này.
Xử lý và thử lại: Kiểm tra mã đích, chủ sở hữu tài nguyên và workspace hiện tại. Không coi đích đã xác nhận thiếu hoặc không truy cập được là lỗi dịch vụ tạm thời để tự thử lại.
JSON minh họa; message thay đổi theo nguyên nhân thực tế · 404 · 20020
{ "request_id": "req_example", "error": { "code": "account_not_found", "numeric_code": "20020", "message": "Account not found" } }- target_workspace_not_found · 11004 · 404
Không tìm thấy workspace được ghi đè hoặc workspace không khả dụng. Kiểm tra chủ sở hữu, bỏ tiêu đề ghi đè và dùng API Key của workspace đích; gọi lặp không cấp thêm quyền.
Điều kiện: Áp dụng khi yêu cầu có tiêu đề X-Workspace-Id để ghi đè workspace.
Xử lý và thử lại: Kiểm tra mã đích, chủ sở hữu tài nguyên và workspace hiện tại. Không coi đích đã xác nhận thiếu hoặc không truy cập được là lỗi dịch vụ tạm thời để tự thử lại.
JSON minh họa; message thay đổi theo nguyên nhân thực tế · 404 · 11004
{ "request_id": "req_example", "error": { "code": "target_workspace_not_found", "numeric_code": "11004", "message": "Target workspace not found" } }- deactivate_webhook_endpoint_failed · 40004 · 500
Vô hiệu hoá điểm cuối Webhook: chưa xác nhận đã dừng hoặc vô hiệu hóa; xử lý tiếp phải giữ đúng mục tiêu dừng ban đầu.
Xử lý và thử lại: Kiểm tra trạng thái để xác nhận đã dừng hoặc vô hiệu hóa chưa. Không khởi động hay kết nối lại tài nguyên vốn định dừng.
JSON minh họa; message thay đổi theo nguyên nhân thực tế · 500 · 40004
{ "request_id": "req_example", "error": { "code": "deactivate_webhook_endpoint_failed", "numeric_code": "40004", "message": "Failed to deactivate webhook endpoint" } }- deactivate_webhook_endpoint_failed · 40006 · 500
Không tìm thấy đầu nhận Webhook trong phạm vi này. GET, PATCH và vô hiệu hóa giữ code theo thao tác cùng HTTP 500, bổ sung numeric_code=40006. Chi tiết này không áp dụng cho DELETE có tính lũy đẳng: đầu nhận không tồn tại vẫn trả 204.
Xử lý và thử lại: Kiểm tra mã đích, chủ sở hữu tài nguyên và workspace hiện tại. Không coi đích đã xác nhận thiếu hoặc không truy cập được là lỗi dịch vụ tạm thời để tự thử lại.
JSON minh họa; message thay đổi theo nguyên nhân thực tế · 500 · 40006
{ "request_id": "req_example", "error": { "code": "deactivate_webhook_endpoint_failed", "numeric_code": "40006", "message": "Webhook endpoint not found" } }