Webhook Endpoint

Tạo điểm cuối Webhook

Tạo Webhook tại URL HTTP(S) tuyệt đối; production nên dùng HTTPS. status là active hoặc inactive. subscribed_events nhận public event hoặc ["*"]; max_attempts 0..5. Tạo endpoint active của tài khoản khi cùng tài khoản đã có endpoint active khác trả về 409 account_webhook_already_exists (40008). Quyền nhận sự kiện gọi do is_beta của không gian làm việc quyết định. Với quyền thử nghiệm, subscribed_events là *, rỗng hoặc bị bỏ qua bao gồm sự kiện gọi; danh sách cụ thể chỉ nhận các sự kiện đã liệt kê. Không gian không có quyền vẫn dùng được wildcard nhưng không nhận sự kiện gọi; đăng ký rõ sự kiện gọi trả về 403 beta_feature_not_enabled. Quyền được kiểm tra lại mỗi lần gửi, thử lại và phát lại dead letter; lỗi tra cứu không cho phép gửi. Bản ghi cuộc gọi message.* thông thường độc lập.

POSThttps://api.unifyport.ai/v1/webhook-endpoints

Kênh được hỗ trợ

all

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.

Khi tạo hoặc kích hoạt lại điểm nhận riêng của tài khoản, mỗi account_id chỉ được có một điểm nhận active; xung đột trả 409 account_webhook_already_exists (40008). Có thể có nhiều điểm nhận tài khoản inactive và điểm nhận của không gian làm việc. Điểm nhận đang active vẫn được cập nhật khi giữ active, kể cả cấu hình cũ có nhiều điểm nhận active.

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

Yêu cầu

curl -X POST "https://api.unifyport.ai/v1/webhook-endpoints" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhook",
  "status": "active",
  "subscribed_events": ["*"],
  "signing_secret": "<WEBHOOK_SIGNING_SECRET>"
}'

Tham số yêu cầu

Tiêu đề

X-Api-Key

stringbắt buộc

API 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.

Content-Type

stringbắt buộc

Dùng application/json khi gửi nội dung yêu cầu JSON.

Nội dung yêu cầu

account_id

string

ID tài khoản công khai tùy chọn trong body, ví dụ acc_example. Khi tạo, liên kết endpoint với tài khoản; bỏ qua thì tạo endpoint của không gian làm việc. Khi cập nhật, chỉ kiểm tra liên kết ban đầu; bỏ qua thì giữ nguyên chủ sở hữu. Không thể đổi tài khoản, chuyển endpoint của không gian làm việc thành endpoint của tài khoản hoặc xóa liên kết. Không chấp nhận query, null, chuỗi rỗng, chuỗi chỉ chứa khoảng trắng hoặc trường lặp lại. Tên trường phải đúng là account_id; biến thể chữ hoa/chữ thường trong body hoặc query và chủ sở hữu 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). Cấu hình độc lập của tài khoản được ưu tiên hơn cấu hình không gian làm việc. Vô hiệu hóa hoặc không đăng ký một loại sự kiện không chuyển về cấu hình không gian làm việc. Xóa endpoint độc lập cuối cùng sẽ khôi phục kế thừa cho các lần gửi ban đầu sau đó. Kiểm tra xung đột kích hoạt chỉ áp dụng với endpoint active khác có cùng account_id; endpoint của không gian làm việc không bị giới hạn này. Xem điều kiện ở status.

minLength: 1 · pattern: \S

url

stringbắt buộc

URL HTTP(S) tuyệt đối nhận Webhook; production nên dùng HTTPS.

format: uri

status

stringbắt buộc

Trạng thái endpoint: active hoặc inactive. Tạo endpoint active của tài khoản hoặc đổi inactive→active khi cùng tài khoản có endpoint active khác trả về 409 account_webhook_already_exists (40008). Có thể có nhiều endpoint inactive của tài khoản và nhiều endpoint của không gian làm việc. Endpoint active hiện có vẫn được cập nhật và giữ active, kể cả cấu hình cũ có nhiều endpoint active; không tự động dọn dẹp các endpoint cũ.

enum: active, inactive

subscribed_events[]

string[]

Đăng ký public standard event. Bỏ qua, mảng rỗng hoặc chứa * nghĩa là nhận mọi public event, kể cả contact.updated mới được thêm, nhưng không gồm provider.raw_event. Liệt kê rõ tên event nếu chỉ muốn nhận các event được chọn.

signing_secret

string

Secret ký Webhook tuỳ chọn. Dùng placeholder trong ví dụ.

retry_policy

object

max_attempts là số lần retry sau lần gửi đầu, mặc định 3, phạm vi 0–5; 0 chỉ gửi lần đầu.

max_attempts

integer

Số lần retry sau lần gửi đầu, từ 0 đến 5.

Hiểu kết quả

Kiểm tra cấu hình trả về. Để thử giao sự kiện, điểm nhận phải active và đăng ký sự kiện liên quan. Chỉ xác minh chữ ký khi signing_enabled=true; lưu sự kiện trước rồi trả 2xx để xác nhận.

Phản hồi 201 Created

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "id": "we_example",
    "url": "https://example.com/webhook",
    "status": "active",
    "subscribed_events": [
      "*"
    ],
    "signing_enabled": true,
    "retry_policy": {
      "max_attempts": 3
    }
  }
}

Nội dung phản hồi

id

string

Định danh điểm cuối webhook (we_...).

account_id

string

ID 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

url

string

URL HTTP(S) tuyệt đối nhận webhook; production nên dùng HTTPS.

format: uri

status

string

Trạng thái điểm cuối: active hoặc inactive.

enum: active, inactive

subscribed_events[]

string[]

Public standard event của điểm cuối; ["*"] nghĩa là mọi public event, không gồm provider.raw_event.

signing_enabled

boolean

true khi đã đặt secret ký và các lượt gửi được ký.

retry_policy

object

max_attempts đếm retry sau lần gửi đầu, mặc định 3, phạm vi 0–5.

max_attempts

integer

Số lần retry đã cấu hình sau lần gửi đầu, từ 0 đến 5.

Phản hồi

201

201 Created

Yêu cầu thành công. Xem ví dụ nội dung phản hồi.

400

Bad Request

Body, đường dẫn hoặc tham số yêu cầu không hợp lệ.

401

Unauthorized

Header X-Api-Key thiếu hoặc không hợp lệ.

403

Forbidden

Yêu cầu đã được nhận diện nhưng thao tác không được phép.

404

Not 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.

409

Conflict

Thao tác đang yêu cầu xung đột với tài khoản hoặc tài nguyên nhà cung cấp đã có.

500

Internal 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"
  }
}

beta_feature_not_enabled · 41002 · 403

Không gian làm việc cần quyền thử nghiệm kín để dùng API cuộc gọi và đăng ký rõ các sự kiện cuộc gọi.

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ụ · 403 · 41002

{
  "request_id": "req_example",
  "error": {
    "code": "beta_feature_not_enabled",
    "numeric_code": "41002",
    "message": "Beta feature not enabled"
  }
}

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.

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"
  }
}

account_webhook_already_exists · 40008 · 409

Dùng account_id để liệt kê các điểm nhận riêng của tài khoản và cập nhật điểm nhận active hiện có. Để chuyển, vô hiệu hóa điểm nhận active cũ trước rồi kích hoạt điểm nhận khác. Không tự động thử lại việc tạo hoặc kích hoạt lại.

Xử lý và thử lại: Đọc cấu hình đầu nhận và phạm vi tài khoản trước khi gửi lại. PATCH thay thế thiết lập; giữ đủ đăng ký, chữ ký và chính sách thử lại cần dùng. Nếu xung đột đầu nhận active, cập nhật cái hiện có hoặc vô hiệu hóa nó trước khi bật cái khác.

Ví dụ · 409 · 40008

{
  "request_id": "req_example_webhook_conflict",
  "error": {
    "code": "account_webhook_already_exists",
    "numeric_code": "40008",
    "message": "Account already has an active webhook endpoint"
  }
}

create_webhook_endpoint_failed · 40001 · 500

Tạo điểm cuối Webhook: lỗi chưa phân loại làm gián đoạn thay đổi; cần xác nhận trạng thái tài nguyên cuối cùng.

JSON minh họa; message thay đổi theo nguyên nhân thực tế · 500 · 40001

{
  "request_id": "req_example",
  "error": {
    "code": "create_webhook_endpoint_failed",
    "numeric_code": "40001",
    "message": "Failed to create webhook endpoint"
  }
}