API Webhooks

Webhooks cho phép nền tảng thông báo cho các hệ thống khác của bạn ngay khi có sự kiện xảy ra — một liên hệ mới, một phản hồi, một cuộc hẹn đã đặt, và nhiều hơn nữa. API này quản lý chính các đăng ký: URL nào nhận sự kiện nào. Để biết cách nhận và xác minh các payload mà endpoint của bạn nhận được, hãy xem Webhooks.

Tất cả các đường dẫn bên dưới đều tương đối so với URL cơ sở của API:

https://api.youraiconnector.com/v1

Mọi yêu cầu đều phải được xác thực. Xem Xác thực để biết bốn phương thức được chấp nhận. Các ví dụ ở đây sử dụng tiêu đề X-API-Key (và một dạng tham số truy vấn cho cURL).

Lưu ý: Webhook phải được bật cho tài khoản của bạn. Nếu chưa, các điểm cuối này sẽ trả về 403.

Cách định địa chỉ cho các đăng ký

Mỗi đăng ký có một id và một name tùy chọn. Cả hai đều có thể được sử dụng làm {webhookId} trong đường dẫn để cập nhật, xóa, kiểm tra, kiểm tra trạng thái và kích hoạt lại.

Nên ưu tiên sử dụng tên. ID đăng ký mang tính vị trí, vì vậy chúng có thể thay đổi sau khi một đăng ký khác bị xóa. Nếu bạn đặt một name ổn định khi tạo đăng ký, hãy định địa chỉ theo tên để tránh các bất ngờ.

Liệt kê các đăng ký

GET /webhooks

cURL

curl "https://api.youraiconnector.com/v1/webhooks?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/webhooks", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/webhooks",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "webhooks": [
    {
      "id": "0",
      "name": "Order updates hook",
      "url": "https://hooks.example.com/incoming",
      "subscribed_to": ["Contact Created", "Replies"],
      "subscribed_to_tags": [],
      "created_at": "2026-06-09T12:00:00.000Z",
      "signing_enabled": true,
      "signing_secret_created_at": "2026-07-15T09:30:00.000Z",
      "retries_enabled": true,
      "enabled": true,
      "apply_to_sub_accounts": false
    }
  ]
}

signing_enabled và retries_enabled là các tùy chọn đăng ký theo gói, cả hai đều tắt trừ khi bạn bật chúng lên. Xem Payload đã ký và Thử lại.

apply_to_sub_accounts là tùy chọn kế thừa đại lý — xem Một gói đăng ký cho tất cả tài khoản khách hàng. Mặc định là tắt và không hoạt động trên các tài khoản không có tài khoản khách hàng nào.

enabled là công tắc bật/tắt của gói đăng ký — xem Tắt gói đăng ký. Các gói đăng ký đã tắt vẫn được liệt kê tại đây.

Bản thân bí mật ký (signing secret) không bao giờ được bao gồm ở đây — hãy đọc nó từ GET /webhooks/{id}/signing-secret.

Liệt kê các loại sự kiện có thể đăng ký

Trả về các chuỗi chính xác mà bạn có thể sử dụng trong subscribed_to. Hãy sử dụng tính năng này để khám phá các tên sự kiện hợp lệ thay vì mã hóa cứng chúng.

GET /webhooks/events

cURL

curl "https://api.youraiconnector.com/v1/webhooks/events" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/webhooks/events", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/webhooks/events",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Phản hồi

Phản hồi là {"success": true, "events": [...]}, trong đó events hiện đang chứa 22 chuỗi chính xác: Contact Created, Human Alerted, Appointment Booked, Replies, Reads, Deliveries, Credits Spent, Credits Recharged, Low Credit Balance, Contact Paused, Contact Do Not Disturb, Contact Unarchived, New Message, Contact Resumed, Chat Concluded, Task Created, Task Updated, Task Completed, Daily Summary Created, Channel Connected, Broadcast Started, và Broadcast Completed (Channel Connected được chấp nhận trong subscribed_to nhưng hiện tại không có gì phát ra nó, vì vậy đừng xây dựng dựa trên nó).

Để biết ý nghĩa của từng sự kiện và mã event mà nó gửi trong payload, hãy xem 22 Sự kiện Webhook. Endpoint này là danh sách có thẩm quyền tại bất kỳ thời điểm nào — hãy đọc trực tiếp thay vì mã hóa cứng các tên.

Tạo một đăng ký

POST /webhooks

Trường	Bắt buộc	Mô tả
`url`	Có	URL HTTPS sẽ nhận payload sự kiện qua `POST`. Phải có thể truy cập công khai.
`subscribed_to`	Có	Một mảng không rỗng các tên sự kiện (xem `/webhooks/events`).
`name`	Không	Tên hiển thị. Cũng có thể sử dụng làm `{webhookId}` sau này. Mặc định là tên có dấu thời gian.
`subscribed_to_tags`	Không	ID thẻ giúp thu hẹp các thẻ nào tạo ra thông báo tóm tắt cuộc trò chuyện. Nó không giới hạn các sự kiện của gói đăng ký vào các thẻ đó — để nhận yêu cầu khi một thẻ cụ thể được áp dụng, hãy đặt URL webhook trên thẻ đó trong tab Thẻ của đại lý (hoặc chiến dịch).
`retries_enabled`	Không	Boolean, mặc định là `false`. Chọn tham gia thử lại các lần gửi thất bại.
`generate_signing_secret`	Không	Boolean, mặc định là `false`. Tạo một bí mật ký HMAC với gói đăng ký. Bí mật được trả về một lần, dưới dạng `signing_secret` cấp cao nhất trong phản hồi.
`enabled`	Không	Boolean, mặc định là `true`. Truyền `false` để tạo gói đăng ký ở trạng thái tắt. Xem Tắt gói đăng ký.
`apply_to_sub_accounts`	Không	Boolean, mặc định là `false`. Trên tài khoản đại lý, `true` giúp gói đăng ký này cũng nhận được sự kiện từ mọi tài khoản khách hàng — xem Một gói đăng ký cho tất cả tài khoản khách hàng.

Quy tắc URL: URL phải sử dụng https:// và có thể truy cập công khai. Các địa chỉ http://, localhost thuần túy, địa chỉ mạng nội bộ và địa chỉ nội bộ của nền tảng sẽ bị từ chối với mã 400.

cURL

curl -X POST "https://api.youraiconnector.com/v1/webhooks?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "name": "Order updates hook"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/webhooks", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://hooks.example.com/incoming",
    subscribed_to: ["Contact Created", "Replies"],
    name: "Order updates hook",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/webhooks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "url": "https://hooks.example.com/incoming",
        "subscribed_to": ["Contact Created", "Replies"],
        "name": "Order updates hook",
    },
)
data = res.json()

Phản hồi

{
  "success": true,
  "webhook_id": "1",
  "webhook": {
    "id": "1",
    "name": "Order updates hook",
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "subscribed_to_tags": [],
    "created_at": "2026-06-09T12:00:00.000Z"
  }
}

Cập nhật đăng ký

Cung cấp ít nhất một trong các trường url, subscribed_to, name, subscribed_to_tags, retries_enabled, enabled hoặc apply_to_sub_accounts. Các trường bị bỏ qua sẽ giữ nguyên giá trị hiện tại. subscribed_to và subscribed_to_tags là các thay thế, không phải hợp nhất.

PUT /webhooks/{webhookId}

Việc cập nhật đăng ký không bao giờ làm ảnh hưởng đến bí mật ký của nó — hãy quản lý điều đó thông qua các tuyến đường bí mật ký.

Khi URL thay đổi, việc gửi dữ liệu cho URL mới sẽ tự động được kích hoạt lại, giúp một điểm cuối từng bị lỗi có một khởi đầu mới.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/webhooks/Order%20updates%20hook" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/v2/incoming",
    "subscribed_to": ["Replies", "Chat Concluded"]
  }'

JavaScript

const res = await fetch(
  `https://api.youraiconnector.com/v1/webhooks/${encodeURIComponent("Order updates hook")}`,
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: "https://hooks.example.com/v2/incoming",
      subscribed_to: ["Replies", "Chat Concluded"],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/webhooks/Order updates hook",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "url": "https://hooks.example.com/v2/incoming",
        "subscribed_to": ["Replies", "Chat Concluded"],
    },
)
data = res.json()

Phản hồi

{
  "success": true,
  "webhook_id": "0",
  "webhook": {
    "id": "0",
    "name": "Order updates hook",
    "url": "https://hooks.example.com/v2/incoming",
    "subscribed_to": ["Replies", "Chat Concluded"],
    "subscribed_to_tags": [],
    "created_at": "2026-06-09T12:00:00.000Z"
  }
}

Một id hoặc tên không xác định sẽ trả về 404 kèm theo { "success": false, "error": "Webhook not found" }.

Xóa đăng ký

Xóa đăng ký để URL của nó ngừng nhận payload. Các bộ đếm trạng thái gửi dữ liệu của nó sẽ được đặt lại, vì vậy việc thêm lại cùng một URL sau này sẽ bắt đầu với một hồ sơ sạch.

DELETE /webhooks/{webhookId}

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/webhooks/0" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0", {
  method: "DELETE",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/webhooks/0",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Phản hồi

{
  "success": true
}

Gửi payload kiểm thử

Gửi một payload mẫu đến URL của đăng ký để bạn có thể xác minh đầu thu của mình từ đầu đến cuối. Tùy chọn truyền vào một event để kiểm soát loại sự kiện mà mẫu sẽ mô phỏng. Các lần gửi kiểm thử không bao giờ ảnh hưởng đến bộ đếm trạng thái của đăng ký.

POST /webhooks/{webhookId}/test

Phản hồi luôn trả về 200 và báo cáo kết quả với cờ delivered — một bài kiểm thử thất bại không trả về trạng thái lỗi. Khi delivered là false, phản hồi sẽ bao gồm chi tiết về lỗi.

Trường	Bắt buộc	Mô tả
`event`	Không	Loại sự kiện cần mô phỏng (phải là một trong các `/webhooks/events`). Mặc định là sự kiện gửi dữ liệu.

cURL

curl -X POST "https://api.youraiconnector.com/v1/webhooks/0/test?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "event": "Contact Created" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0/test", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ event: "Contact Created" }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/webhooks/0/test",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"event": "Contact Created"},
)
data = res.json()

Phản hồi (đã gửi)

{
  "success": true,
  "webhook_id": "0",
  "delivered": true
}

Phản hồi (thất bại)

{
  "success": true,
  "webhook_id": "0",
  "delivered": false,
  "failure_type": "permanent",
  "status_code": 404,
  "error_message": "Request failed with status code 404"
}

failure_type là một trong số permanent, temporary, timeout, network, hoặc unknown.

Kiểm tra trạng thái gửi

Trả về bản ghi trạng thái gửi cho URL của đăng ký: số lượng lần gửi thành công và thất bại, liệu việc gửi có đang bị tạm dừng sau các lần thất bại liên tiếp hay không, và chi tiết về lần thất bại gần nhất. Trả về "health": null khi chưa có lần gửi nào được thực hiện.

GET /webhooks/{webhookId}/health

cURL

curl "https://api.youraiconnector.com/v1/webhooks/0/health" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0/health", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/webhooks/0/health",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "webhook_id": "0",
  "url": "https://hooks.example.com/incoming",
  "health": {
    "consecutive_failures": 0,
    "total_failures": 2,
    "total_successes": 120,
    "is_disabled": false,
    "disabled_at": null,
    "disabled_reason": null,
    "last_failure": null,
    "last_success_at": "2026-06-09T12:00:00.000Z",
    "created_at": "2026-05-01T08:00:00.000Z",
    "updated_at": "2026-06-09T12:00:00.000Z"
  }
}

Khi is_disabled là true, việc gửi đến URL đã bị tạm dừng tự động sau các lần thất bại liên tiếp. Hãy sửa bộ nhận của bạn, sau đó kích hoạt lại (bên dưới).

Kích hoạt lại việc gửi

Tiếp tục gửi cho webhook có URL đã bị tạm dừng tự động sau các lần thất bại liên tiếp. Thao tác này sẽ đặt lại cờ tạm dừng và bộ đếm lỗi nhưng không thực hiện gửi lại — hãy sử dụng endpoint kiểm thử sau đó để xác nhận bộ nhận của bạn đã hoạt động bình thường trở lại.

POST /webhooks/{webhookId}/reenable

cURL

curl -X POST "https://api.youraiconnector.com/v1/webhooks/0/reenable?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0/reenable", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/webhooks/0/reenable",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "webhook_id": "0"
}

Tắt gói đăng ký

enabled là công tắc bật/tắt của chính gói đăng ký. Việc tắt nó sẽ dừng gửi thông báo trong khi vẫn giữ nguyên URL, danh sách sự kiện và bí mật ký.

# Off
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

# Back on
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

Vắng mặt nghĩa là bật. Một gói đăng ký được tạo trước khi trường này tồn tại sẽ không có giá trị enabled được lưu trữ và vẫn gửi thông báo bình thường. GET /webhooks luôn báo cáo một giá trị boolean cụ thể.
Các gói đăng ký đã tắt vẫn được liệt kê bởi GET /webhooks — đó là cách bạn tìm thấy chúng để bật lại.
Một lần thử lại được xếp hàng trước khi tắt sẽ không tiếp tục: quá trình thử lại sẽ đọc lại gói đăng ký tại thời điểm gửi và hủy nếu nó đang ở trạng thái tắt.
Không có gì bị chặn trong khi tắt được phát lại khi bạn bật lại.

Khác biệt với việc tự động vô hiệu hóa sau nhiều lần thất bại liên tiếp, được báo cáo bởi GET /webhooks/{id}/health dưới dạng is_disabled và được xóa bằng POST /webhooks/{id}/reenable. enabled là công tắc của tài khoản; is_disabled là công tắc của chúng tôi. Không cái nào ghi đè cái nào — một gói đăng ký phải vừa được bật vừa không bị tự động vô hiệu hóa thì mới có thể gửi thông báo.

Một gói đăng ký cho tất cả tài khoản khách hàng (đại lý)

Trên tài khoản đại lý, hãy đặt apply_to_sub_accounts: true trên gói đăng ký (tại thời điểm tạo hoặc qua PUT) và nó cũng sẽ nhận được các sự kiện xảy ra trên mọi tài khoản khách hàng của đại lý — một endpoint bao quát toàn bộ đại lý, thay vì phải tạo lại gói đăng ký trên từng tài khoản khách hàng.

curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"apply_to_sub_accounts": true}'

Cách thức hoạt động:

Khối user giúp phân biệt các tài khoản. Khối user của mỗi payload xác định tài khoản nơi sự kiện thực sự xảy ra, vì vậy trình nhận của bạn có thể định tuyến theo từng khách hàng.
Các cài đặt riêng của gói đăng ký đại lý được áp dụng ở mọi nơi. Danh sách sự kiện, bí mật ký và tùy chọn thử lại của nó cũng được sử dụng cho các lần gửi được kế thừa.
Gói đăng ký riêng của tài khoản khách hàng cho cùng một URL sẽ được ưu tiên. Nếu một tài khoản khách hàng có gói đăng ký riêng trỏ đến cùng một URL, gói đó sẽ được sử dụng cho các sự kiện của tài khoản đó — cùng một sự kiện không bao giờ được gửi hai lần đến một endpoint.
Tài khoản khách hàng không nhìn thấy nó. Các gói đăng ký được kế thừa không xuất hiện trong danh sách webhook riêng của tài khoản khách hàng và khách hàng không thể tắt chúng — chỉ đại lý mới quản lý được.
Tình trạng gửi được theo dõi theo từng tài khoản khách hàng. Một endpoint liên tục thất bại sẽ tự động bị vô hiệu hóa đối với tài khoản có lần gửi thất bại, không phải cho toàn bộ đại lý.
subscribed_to_tags không được kế thừa. Danh sách thẻ tham chiếu đến các thẻ riêng của đại lý, vốn không tồn tại trên các tài khoản khách hàng — việc thu hẹp tóm tắt cuộc trò chuyện chỉ áp dụng cho các sự kiện riêng của đại lý.
Không hoạt động ở nơi khác. Trên tài khoản không có tài khoản khách hàng nào, cờ này được lưu trữ bình thường và không có tác dụng gì.

Các tiêu đề trên mỗi lần gửi

Ba tiêu đề này được gửi trong mỗi lần gửi, bất kể đăng ký có được ký hay không:

Tiêu đề	Ý nghĩa
`X-Webhook-Delivery`	ID ổn định cho sự kiện logic. Giống hệt nhau giữa các lần thử lại — hãy khử trùng lặp dựa trên nó.
`X-Webhook-Attempt`	Số lần thử bắt đầu từ 1.
`X-Webhook-Event`	Tên sự kiện.

Payload đã ký

Việc ký là tùy chọn, mặc định là tắt và được thiết lập cho mỗi đăng ký. Khi một đăng ký có bí mật ký, mỗi lần gửi sẽ mang thêm hai tiêu đề nữa ngoài ba tiêu đề được gửi trên mỗi lần gửi (X-Webhook-Delivery, X-Webhook-Attempt và X-Webhook-Event):

Tiêu đề	Ý nghĩa
`X-Webhook-Signature`	`v1=<hex>` — HMAC-SHA256 của chuỗi `"<timestamp>.<raw request body>"`, được khóa bằng bí mật ký cho mỗi webhook mà bạn tạo và xoay vòng tại `GET/POST/DELETE /v1/webhooks/{webhookId}/signing-secret`.
`X-Webhook-Timestamp`	Thời gian gửi, tính bằng giây Unix. Được gắn vào chữ ký, vì vậy nó không thể bị thay đổi độc lập.

Để xác minh, hãy tính toán lại HMAC-SHA256 trên nội dung thô bằng bí mật của bạn và so sánh nó với tiêu đề. Xác minh dựa trên nội dung yêu cầu thô. Việc tuần tự hóa lại JSON đã phân tích cú pháp sẽ làm thay đổi các byte và phá vỡ quá trình so sánh. Hãy từ chối các lần gửi có dấu thời gian nằm ngoài cửa sổ mới (300 giây là mặc định hợp lý) để ngăn chặn phát lại và so sánh bằng hàm an toàn về thời gian.

Xem Payload đã ký để biết các ví dụ xác minh đầy đủ bằng Node và Python.

Ký không giống như xác thực API. Bản thân REST API xác thực bằng khóa API thay vì OAuth (OAuth 2.1 tồn tại cho các máy chủ MCP mà bạn đăng ký làm công cụ bot), và hiện chưa có gói SDK npm hoặc PyPI chính thức nào — hãy gọi các endpoint bằng bất kỳ trình khách HTTP nào.

Đọc bí mật ký

GET /webhooks/{id}/signing-secret

curl "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "webhook_id": "0",
  "signing_enabled": true,
  "signing_secret": "whsec_1a2b3c...",
  "signing_secret_created_at": "2026-07-15T09:30:00.000Z"
}

Khi tính năng ký bị tắt, signing_enabled là false và signing_secret là null.

Tạo hoặc xoay vòng bí mật ký

POST /webhooks/{id}/signing-secret

Tạo một bí mật (bật tính năng ký) hoặc thay thế bí mật hiện có. Trả về bí mật mới.

curl -X POST "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "webhook_id": "0",
  "signing_enabled": true,
  "signing_secret": "whsec_9f8e7d...",
  "signing_secret_created_at": "2026-07-15T10:00:00.000Z"
}

Việc xoay vòng có hiệu lực ngay lập tức — lần gửi tiếp theo chỉ được ký bằng bí mật mới. Hãy chấp nhận cả hai bí mật trong thời gian ngắn trong khi bạn triển khai thay đổi tới điểm cuối trực tiếp.

Bạn cũng có thể tạo bí mật tại thời điểm tạo bằng cách truyền "generate_signing_secret": true vào POST /webhooks; phản hồi sau đó sẽ bao gồm trường signing_secret ở cấp cao nhất.

Tắt tính năng ký

DELETE /webhooks/{id}/signing-secret

curl -X DELETE "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "webhook_id": "0",
  "signing_enabled": false
}

Tất cả ba tuyến đường bí mật ký đều yêu cầu quyền chỉnh sửa Tích hợp, bao gồm cả GET — bí mật là thông tin xác thực có thể giả mạo các lần gửi, vì vậy nó không được hiển thị cho các vai trò chỉ đọc.

Thử lại

Tùy chọn, mặc định là tắt và được thiết lập cho mỗi đăng ký thông qua boolean retries_enabled trên POST /webhooks hoặc PUT /webhooks/{id}.

curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"retries_enabled": true}'

Khi được bật, một lần gửi thất bại sẽ được thử lại sau 1 phút, 5 phút, 30 phút và 2 giờ kể từ lần thử đầu tiên (tổng cộng khoảng 2 giờ 40 phút).

Được thử lại: các phản hồi 5xx, hết thời gian chờ và lỗi kết nối.
Không được thử lại: bất kỳ phản hồi 4xx nào. Người nhận đang tự từ chối yêu cầu, vì vậy việc phát lại yêu cầu đó mà không thay đổi chỉ lặp lại sự từ chối.

Việc thử lại có thể dẫn đến phân phối trùng lặp — một endpoint đã xử lý sự kiện nhưng hết thời gian chờ trước khi phản hồi sẽ nhận lại sự kiện đó. Hãy khử trùng lặp dựa trên X-Webhook-Delivery, vốn không đổi qua các lần thử. Đây là lý do tại sao việc thử lại là tùy chọn (opt-in).

Các bộ đếm delivery-health đếm toàn bộ một lần gửi, không phải từng lần thử: lỗi chỉ được ghi lại một lần sau khi tất cả các lần thử đã cạn kiệt, vì vậy việc bật thử lại không làm cho trình kích hoạt tự động vô hiệu hóa xảy ra sớm hơn.

Lỗi

Tất cả các lỗi đều sử dụng cấu trúc chuẩn:

{
  "success": false,
  "error": "Webhook not found"
}

Các trường hợp phổ biến: URL không được phép, subscribed_to trống/không hợp lệ, hoặc thiếu các trường sẽ trả về 400; id hoặc tên không xác định sẽ trả về 404; và 403 có nghĩa là webhook chưa được bật cho tài khoản của bạn. Xem Lỗi để biết danh sách đầy đủ.

Các bước tiếp theo

Webhooks (nhận payload) — thiết lập bộ thu của bạn và tìm hiểu cấu trúc payload.
Xác thực — bốn cách để xác thực một yêu cầu.
Lỗi & Giới hạn tốc độ — các mã trạng thái và giới hạn 300 yêu cầu/phút.

API Webhooks #

Cách định địa chỉ cho các đăng ký #

Liệt kê các đăng ký #

Liệt kê các loại sự kiện có thể đăng ký #

Tạo một đăng ký #

Cập nhật đăng ký #

Xóa đăng ký #

Gửi payload kiểm thử #

Kiểm tra trạng thái gửi #

Kích hoạt lại việc gửi #

Tắt gói đăng ký #

Một gói đăng ký cho tất cả tài khoản khách hàng (đại lý) #

Các tiêu đề trên mỗi lần gửi #

Payload đã ký #

Đọc bí mật ký #

Tạo hoặc xoay vòng bí mật ký #

Tắt tính năng ký #

Thử lại #

Lỗi #

Các bước tiếp theo #

API Webhooks

Cách định địa chỉ cho các đăng ký

Liệt kê các đăng ký

Liệt kê các loại sự kiện có thể đăng ký

Tạo một đăng ký

Cập nhật đăng ký

Xóa đăng ký

Gửi payload kiểm thử

Kiểm tra trạng thái gửi

Kích hoạt lại việc gửi

Tắt gói đăng ký

Một gói đăng ký cho tất cả tài khoản khách hàng (đại lý)

Các tiêu đề trên mỗi lần gửi

Payload đã ký

Đọc bí mật ký

Tạo hoặc xoay vòng bí mật ký

Tắt tính năng ký

Thử lại

Lỗi

Các bước tiếp theo