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.

Xem Markdown

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

MethodEndpointMô tả
POST/v1/webhooksĐăng ký một điểm cuối webhook
GET/v1/webhooksDanh sách webhook đã đăng ký
DELETE/v1/webhooks/{id}Xoá đăng ký webhook

Kiểm thử tại chỗ

POSThttps://crm-gateways.hitechcloud.vn/v1/webhooks

Gửi thử sẽ đăng ký webhook thật. Token không được lưu lại.

Body
cURL đăng ký webhook
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"
  }'
Phản hồi (201 Created)
{
  "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ý.

Xác thực chữ ký webhook (Node.js)
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));
}
Hãy phản hồi HTTP 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ờ.