Webhook — Tổng quan & Đăng ký
Webhook HiTechCloud CRM: đăng ký endpoint để nhận thông báo thời gian thực khi liên hệ, công ty, cơ hội hay hoạt động trong CRM thay đổi.
Webhook giúp hệ thống của bạn nhận thông báo tức thời khi liên hệ, cơ hội hay hoạt động thay đổi, thay vì phải hỏi API liên tục (polling). HiTechCloud CRM gửi sự kiện tới URL của bạn bằng HTTP POST.
Đăng ký webhook
| Method | Endpoint | Mô tả |
|---|---|---|
POST | /v1/webhooks | Đăng ký một điểm cuối webhook |
GET | /v1/webhooks | Danh sách webhook đã đăng ký |
DELETE | /v1/webhooks/{id} | Xoá đăng ký webhook |
Kiểm thử tại chỗ
https://crm-gateways.hitechcloud.vn/v1/webhooksKiểm thử tại chỗGửi thử sẽ đăng ký webhook thật. Token không được lưu lại.
curl -X POST "https://crm-gateways.hitechcloud.vn/v1/webhooks" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-app.vn/hooks/crm",
"events": ["contact.created", "deal.won"],
"secret": "whsec_6b3c15aa"
}'{
"status": "success",
"data": {
"id": "wh_3c7f21",
"url": "https://your-app.vn/hooks/crm",
"events": ["contact.created", "deal.won"],
"base_url": "https://crm-gateways.hitechcloud.vn/webhook",
"active": true,
"created_at": "2026-10-31T10:30:00+07:00"
}
}Xác thực chữ ký
Mỗi lần gửi, HiTechCloud CRM đính kèm header X-CRM-Signature chứa chữ ký HMAC-SHA256 của toàn bộ body, ký bằng secret bạn cung cấp. Hãy tính lại chữ ký và so sánh trước khi xử lý.
import crypto from "crypto";
function verify(rawBody: string, signature: string, secret: string) {
const expected = crypto
.createHmac("sha256", secret)
.update(rawBody)
.digest("hex");
return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}2xx trong vòng 5 giây. Nếu điểm cuối lỗi hoặc quá chậm, hệ thống sẽ thử gửi lại theo cơ chế backoff tăng dần tối đa 24 giờ.Webhook giúp hệ thống của bạn nhận thông báo tức thời khi liên hệ, cơ hội hay hoạt động thay đổi, thay vì phải hỏi API liên tục (polling). HiTechCloud CRM gửi sự kiện tới URL của bạn bằng HTTP POST.
Đăng ký webhook
| Method | Endpoint | Mô tả |
|---|---|---|
POST | /v1/webhooks | Đăng ký một điểm cuối webhook |
GET | /v1/webhooks | Danh sách webhook đã đăng ký |
DELETE | /v1/webhooks/{id} | Xoá đăng ký webhook |
Kiểm thử tại chỗ
https://crm-gateways.hitechcloud.vn/v1/webhooksKiểm thử tại chỗGửi thử sẽ đăng ký webhook thật. Token không được lưu lại.
Xác thực chữ ký
Mỗi lần gửi, HiTechCloud CRM đính kèm header X-CRM-Signature chứa chữ ký HMAC-SHA256 của toàn bộ body, ký bằng secret bạn cung cấp. Hãy tính lại chữ ký và so sánh trước khi xử lý.
2xx trong vòng 5 giây. Nếu điểm cuối lỗi hoặc quá chậm, hệ thống sẽ thử gửi lại theo cơ chế backoff tăng dần tối đa 24 giờ.curl -X POST "https://crm-gateways.hitechcloud.vn/v1/webhooks" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-app.vn/hooks/crm",
"events": ["contact.created", "deal.won"],
"secret": "whsec_6b3c15aa"
}'{
"status": "success",
"data": {
"id": "wh_3c7f21",
"url": "https://your-app.vn/hooks/crm",
"events": ["contact.created", "deal.won"],
"base_url": "https://crm-gateways.hitechcloud.vn/webhook",
"active": true,
"created_at": "2026-10-31T10:30:00+07:00"
}
}import crypto from "crypto";
function verify(rawBody: string, signature: string, secret: string) {
const expected = crypto
.createHmac("sha256", secret)
.update(rawBody)
.digest("hex");
return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}