Tham chiếu API

Webhook Endpoint

Cập nhật điểm cuối Webhook

Cập nhật Webhook. url là HTTP(S) tuyệt đối và production nên dùng HTTPS; status là active hoặc inactive. signing_secret rỗng tắt chữ ký; max_attempts 0..5.

PATCHhttps://api.unifyport.ai/v1/webhook-endpoints/{endpoint_id}

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.

PATCH thay thế cấu hình Webhook. Gửi mọi thiết lập cần giữ: bỏ signing_secret sẽ tắt chữ ký; bỏ subscribed_events sẽ nhận lại mọi sự kiện công khai; bỏ retry_policy/max_attempts sẽ khôi phục 3 lần thử lại mặc định. Đọc cấu hình hiện tại trước và cung cấp khóa ký đã lưu.

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.

Tham số đường dẫn

endpoint_id
stringbắt buộc

Định danh dùng cho route webhook endpoints.

Nội dung yêu cầu

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.

enum: active, inactive

subscribed_events[]
string[]

Public standard event được gửi tới điểm cuối. ["*"] đăng ký mọi public event nhưng không gồm provider.raw_event.

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ả

Cấu hình thành công không chứng minh đã giao sự kiện. Tạo sự kiện phù hợp rồi kiểm tra nhận, chữ ký và xác nhận tại máy nhận.

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
string

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

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

200

200 OK

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

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

invalid_request · 10000 · 400
Kiểm tra trường bắt buộc, định dạng và điều kiện kênh rồi sửa yêu cầu.
invalid_api_key · 11001 · 401
Kiểm tra X-Api-Key và workspace còn hoạt động.