Webhook

Webhook cho phép hệ thống của bạn nhận thông báo theo thời gian thực mỗi khi có sự kiện xảy ra trên Mini Gift (nhận quà, hoàn thành khảo sát, tích điểm...). Thay vì phải liên tục gọi API để kiểm tra, Mini Gift sẽ chủ động gửi (POST) dữ liệu đến URL bạn đăng ký.

Xác thực API

Các endpoint quản lý webhook bên dưới yêu cầu header x-api-key. Xem chi tiết tại trang Giới thiệu Open API.

Điều kiện của URL nhận webhook

Bắt buộc dùng HTTPS.
Khi tạo/cập nhật, hệ thống gửi một request xác minh tới URL; URL phải phản hồi HTTP 200 thì mới lưu thành công.
Mỗi cửa hàng chỉ đăng ký được một webhook.

1. Cách webhook hoạt động

Khi một sự kiện phát sinh, Mini Gift gửi một request POST (Content-Type application/json) tới URL của bạn với body:

{
  "event": "gift.claimed",
  "data": { },
  "sentAt": "2026-07-02T02:00:00.000Z"
}

Trường	Kiểu	Mô tả
event	string	Tên sự kiện (xem danh sách bên dưới)
data	object	Dữ liệu chi tiết của sự kiện
sentAt	string (ISO 8601)	Thời điểm gửi

Hệ thống của bạn nên phản hồi HTTP 200 càng nhanh càng tốt (xử lý nặng nên đưa vào hàng đợi nền).

Chính sách gửi lại (Retry) & tự tắt

Thuộc tính	Giá trị
Timeout mỗi lần gọi	10 giây
Số lần thử tối đa	3 lần
Độ trễ giữa các lần thử	ngay lập tức → sau 5 phút → sau 30 phút
Tự động tắt webhook	sau 10 lần thất bại liên tiếp (`active` chuyển `false`)

Chỉ phản hồi 2xx mới được coi là thành công. Mọi mã khác (hoặc timeout) đều tính là thất bại và kích hoạt retry.

2. Danh sách sự kiện hỗ trợ

Endpoint

🔗Endpoint Production

GET https://api.minigift.vn/api/v1/open/webhooks/events

Phản hồi (Response)

{
  "data": [
    "gift.created",
    "gift.updated.info",
    "gift.deleted",
    "gift.claimed",
    "gift.redeemed",
    "gift.claimGiftByExchangePoints",
    "survey.created",
    "survey.updated.info",
    "survey.deleted",
    "survey.completed",
    "points.claimed",
    "user.providedPhone",
    "user.followedOA"
  ],
  "success": true
}

Ý nghĩa các sự kiện

Sự kiện	Kích hoạt khi	data gồm
gift.created	Tạo quà mới	gift
gift.updated.info	Cập nhật thông tin quà	gift
gift.deleted	Xoá quà	gift
gift.claimed	Khách nhận quà	campaignId, userGiftId, userId
gift.redeemed	Khách đổi/sử dụng quà	campaignId, userGiftId, userId
gift.claimGiftByExchangePoints	Đổi quà bằng điểm	userGiftId, userId
survey.created	Tạo khảo sát	survey
survey.updated.info	Cập nhật khảo sát	survey
survey.deleted	Xoá khảo sát	survey
survey.completed	Khách hoàn thành khảo sát	surveyId, campaignId, userId, answers
points.claimed	Khách tích điểm	campaignId, userId
user.providedPhone	Khách cung cấp SĐT	userId, phone
user.followedOA	Khách quan tâm OA	userId, zaloIdByOA

Đăng ký theo nhóm (wildcard)

Có thể dùng ký tự đại diện để đăng ký toàn bộ sự kiện cùng tiền tố, ví dụ gift.* khớp tất cả sự kiện bắt đầu bằng gift.. Hệ thống sẽ tự mở rộng thành danh sách sự kiện cụ thể khi lưu.

Ví dụ payload sự kiện `gift.claimed`

{
  "event": "gift.claimed",
  "data": {
    "campaignId": "6651aa11b2c3d4e5f6a7b8c9",
    "userGiftId": "6652bb22c3d4e5f6a7b8c9d0",
    "userId": "6653cc33d4e5f6a7b8c9d0e1"
  },
  "sentAt": "2026-07-02T02:00:00.000Z"
}

3. Đăng ký Webhook

Endpoint

🔗Endpoint Production

POST https://api.minigift.vn/api/v1/open/webhooks

Dữ liệu được gửi đi (Request Body)

Trường	Kiểu	Bắt buộc	Mô tả
url	string	Có	URL nhận webhook (bắt buộc HTTPS)
events	string[]	Có	Danh sách sự kiện cần nhận (hỗ trợ `gift.*`)
authType	string	Không	`none`, `apikey`, `hmac` (mặc định `hmac`)
headers	object	Không	Header tuỳ chỉnh gửi kèm (dùng với authType = `apikey`)
description	string	Không	Ghi chú mô tả

Ví dụ request

cURL
curl -X POST "https://api.minigift.vn/api/v1/open/webhooks" \
  -H "x-api-key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/webhooks/minigift",
    "events": ["gift.claimed", "survey.completed"],
    "authType": "hmac",
    "description": "Webhook nhận sự kiện quà tặng và khảo sát"
  }'

Request Body
{
  "url": "https://your-domain.com/webhooks/minigift",
  "events": ["gift.claimed", "survey.completed"],
  "authType": "hmac",
  "description": "Webhook nhận sự kiện quà tặng và khảo sát"
}

Phản hồi (Response)

201 Created
409 Conflict
400 Bad Request

{
  "data": {
    "id": "6652ff33a4b5c6d7e8f9a0b1",
    "url": "https://your-domain.com/webhooks/minigift",
    "events": ["gift.claimed", "survey.completed"],
    "authType": "hmac",
    "active": true,
    "secret": "whsec_3f9a1c8e2b7d4a6f0c1e5d8b9a2f7c4e",
    "createdAt": "2026-07-02T02:00:00.000Z"
  },
  "success": true
}

{
  "statusCode": 409,
  "message": "Webhook đã tồn tại cho shop này",
  "error": "Conflict"
}

{
  "statusCode": 400,
  "message": "URL verification failed: expected 200, got 404",
  "error": "Bad Request"
}

4. Lấy thông tin Webhook

Endpoint

🔗Endpoint Production

GET https://api.minigift.vn/api/v1/open/webhooks

Ví dụ request

cURL
curl -X GET "https://api.minigift.vn/api/v1/open/webhooks" \
  -H "x-api-key: sk_your_api_key_here"

Phản hồi (Response)

{
  "data": {
    "id": "6652ff33a4b5c6d7e8f9a0b1",
    "url": "https://your-domain.com/webhooks/minigift",
    "events": ["gift.claimed", "survey.completed"],
    "authType": "hmac",
    "active": true,
    "secret": "whsec_3f9a1c8e2b7d4a6f0c1e5d8b9a2f7c4e",
    "lastTriggeredAt": "2026-07-01T12:34:56.000Z",
    "lastStatus": "success",
    "consecutiveFailures": 0
  },
  "success": true
}

5. Cập nhật Webhook

Endpoint

🔗Endpoint Production

PATCH https://api.minigift.vn/api/v1/open/webhooks/{id}

Tham số đường dẫn (Path Parameters)

Tham số	Kiểu	Bắt buộc	Mô tả
id	string	Có	ID của Webhook

Dữ liệu được gửi đi (Request Body)

Gửi các trường cần cập nhật (tất cả đều tuỳ chọn): url, events, authType, headers, description, active. Nếu cập nhật url, hệ thống sẽ xác minh lại URL (phải trả về 200).

Ví dụ request

cURL
curl -X PATCH "https://api.minigift.vn/api/v1/open/webhooks/6652ff33a4b5c6d7e8f9a0b1" \
  -H "x-api-key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "events": ["gift.*", "points.claimed"], "active": true }'

Request Body
{
  "events": ["gift.*", "points.claimed"],
  "active": true
}

Phản hồi (Response)

{
  "data": {
    "id": "6652ff33a4b5c6d7e8f9a0b1",
    "url": "https://your-domain.com/webhooks/minigift",
    "events": [
      "gift.created",
      "gift.updated.info",
      "gift.deleted",
      "gift.claimed",
      "gift.redeemed",
      "gift.claimGiftByExchangePoints",
      "points.claimed"
    ],
    "active": true,
    "secret": "whsec_3f9a1c8e2b7d4a6f0c1e5d8b9a2f7c4e"
  },
  "success": true
}

6. Làm mới khoá bí mật (Rotate secret)

Tạo lại secret mới cho Webhook. Khoá cũ ngừng hiệu lực ngay lập tức; hãy cập nhật khoá mới vào hệ thống của bạn.

Endpoint

🔗Endpoint Production

POST https://api.minigift.vn/api/v1/open/webhooks/{id}/rotate-secret

Tham số đường dẫn (Path Parameters)

Tham số	Kiểu	Bắt buộc	Mô tả
id	string	Có	ID của Webhook

Ví dụ request

cURL
curl -X POST "https://api.minigift.vn/api/v1/open/webhooks/6652ff33a4b5c6d7e8f9a0b1/rotate-secret" \
  -H "x-api-key: sk_your_api_key_here"

Phản hồi (Response)

{
  "data": {
    "secret": "whsec_a1b2c3d4e5f60718293a4b5c6d7e8f90"
  },
  "success": true
}

7. Gửi thử Webhook (Test)

Gửi một sự kiện mẫu tới URL đã đăng ký để kiểm tra kết nối và cấu hình.

Endpoint

🔗Endpoint Production

POST https://api.minigift.vn/api/v1/open/webhooks/{id}/test

Tham số đường dẫn (Path Parameters)

Tham số	Kiểu	Bắt buộc	Mô tả
id	string	Có	ID của Webhook

Dữ liệu được gửi đi (Request Body)

Trường	Kiểu	Bắt buộc	Mô tả
event	string	Có	Tên sự kiện muốn gửi thử (ví dụ gift.claimed)

Ví dụ request

cURL
curl -X POST "https://api.minigift.vn/api/v1/open/webhooks/6652ff33a4b5c6d7e8f9a0b1/test" \
  -H "x-api-key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "event": "gift.claimed" }'

Request Body
{
  "event": "gift.claimed"
}

Phản hồi (Response)

success cho biết URL của bạn có phản hồi 2xx hay không; httpStatus là mã trạng thái nhận được; duration là thời gian phản hồi (ms).

200 OK
Event không hợp lệ

{
  "data": {
    "success": true,
    "httpStatus": 200,
    "duration": 245
  },
  "success": true
}

{
  "statusCode": 400,
  "message": "Event không hợp lệ: gift.unknown",
  "error": "Bad Request"
}

1. Cách webhook hoạt động​

Chính sách gửi lại (Retry) & tự tắt​

2. Danh sách sự kiện hỗ trợ​

Endpoint​

Phản hồi (Response)​

Ý nghĩa các sự kiện​

Ví dụ payload sự kiện gift.claimed​

3. Đăng ký Webhook​

Endpoint​

Dữ liệu được gửi đi (Request Body)​

Ví dụ request​

Phản hồi (Response)​

4. Lấy thông tin Webhook​

Endpoint​

Ví dụ request​

Phản hồi (Response)​

5. Cập nhật Webhook​

Endpoint​

Tham số đường dẫn (Path Parameters)​

Dữ liệu được gửi đi (Request Body)​

Ví dụ request​

Phản hồi (Response)​

6. Làm mới khoá bí mật (Rotate secret)​

Endpoint​

Tham số đường dẫn (Path Parameters)​

Ví dụ request​

Phản hồi (Response)​

7. Gửi thử Webhook (Test)​

Endpoint​

Tham số đường dẫn (Path Parameters)​

Dữ liệu được gửi đi (Request Body)​

Ví dụ request​

Phản hồi (Response)​

1. Cách webhook hoạt động

Chính sách gửi lại (Retry) & tự tắt

2. Danh sách sự kiện hỗ trợ

Endpoint

Phản hồi (Response)

Ý nghĩa các sự kiện

Ví dụ payload sự kiện `gift.claimed`

3. Đăng ký Webhook

Endpoint

Dữ liệu được gửi đi (Request Body)

Ví dụ request

Phản hồi (Response)

4. Lấy thông tin Webhook

Endpoint

Ví dụ request

Phản hồi (Response)

5. Cập nhật Webhook

Endpoint

Tham số đường dẫn (Path Parameters)

Dữ liệu được gửi đi (Request Body)

Ví dụ request

Phản hồi (Response)

6. Làm mới khoá bí mật (Rotate secret)

Endpoint

Tham số đường dẫn (Path Parameters)

Ví dụ request

Phản hồi (Response)

7. Gửi thử Webhook (Test)

Endpoint

Tham số đường dẫn (Path Parameters)

Dữ liệu được gửi đi (Request Body)

Ví dụ request

Phản hồi (Response)