Webhook sự kiện Hosted Link

Webhook này thông báo tiến trình Hosted Link và trạng thái tài khoản. Webhook giao dịch tiền vào/ra có cấu hình và giao thức riêng.

Cấu hình nơi nhận

Trong Merchant → BankHub → Thiết lập → Webhook event — trạng thái liên kết, lưu URL HTTPS và token webhook. Token gồm 32–128 ký tự chữ, số, _, -; đây là token webhook, không phải API token. Endpoint phải công khai, HTTPS cổng 443; không chuyển hướng sang URL khác.

Một URL có thể nhận cả hai nhóm bên dưới. Phân loại theo event; payload hiện tại không có trường category và không có tùy chọn đăng ký từng nhóm. Return URL chỉ đưa trình duyệt quay lại, không nhận POST webhook.

Hai nhóm sự kiện

Tiến trình phiên

Kết quả và trạng thái tài khoản

Thông báo quan sát trạng thái có account_status, previous_account_status, bank_unlink_confirmed; không suy ra đã hủy phía ngân hàng khi bank_unlink_confirmed=false. Thay đổi từ màn hình Pay2S bên ngoài Hosted Link được phát hiện qua đối soát định kỳ, có thể trễ hơn event phát trực tiếp từ phiên.

Payload mẫu

{
  "event_id": "0123456789abcdef0123456789abcdef",
  "version": "1.0",
  "timestamp": 1791691200,
  "environment": "uat",
  "event": "BANK_ACCOUNT_LINKED",
  "metadata": {
    "session_id": "SESSION_ID",
    "application_id": 2,
    "customer_reference": "CUSTOMER_DEMO",
    "bank_code": "ACB",
    "status": "connected",
    "purpose": "LINK_BANK_ACCOUNT",
    "state": "FINISHED_BANK_ACCOUNT_LINK",
    "unlink_mode": "bank",
    "account": {
      "id": 1,
      "bank_code": "ACB",
      "account_number": "P2S99999999",
      "user_bank_id": 1,
      "simulated": 1
    },
    "bank_profile": "acb_personal",
    "account_type": "personal",
    "connection_type": "openapi"
  },
  "sequence": 1
}

event_id xác định một event và giữ nguyên khi retry. sequence là thứ tự phát sinh, có thể có khoảng trống; không đảm bảo thứ tự nhận. timestamp trong body là lúc tạo event, không đổi khi retry. Giữ số tài khoản dưới dạng chuỗi để bảo toàn số 0 đầu.

Các phiên dùng loại ngân hàng mới có thêm metadata.bank_profile, metadata.account_type (personal, business, household) và metadata.connection_type (openapi, rpa). Những trường này bổ sung thông tin, không chứa username, mật khẩu hoặc OTP. Các phiên ACB cá nhân cũ có thể không có các trường bổ sung.

Xác thực webhook

Content-Type: application/json
Authorization: Bearer WEBHOOK_TOKEN
X-Pay2S-Event-Id: EVENT_ID
X-Pay2S-Timestamp: DELIVERY_UNIX_TIMESTAMP
X-Pay2S-Signature: v1=HEX_HMAC_SHA256

Chữ ký là HMAC-SHA256 với khóa bằng token webhook và chuỗi đầu vào:

X-Pay2S-Timestamp + "." + X-Pay2S-Event-Id + "." + raw_request_body

1. Kiểm tra Bearer token bằng phép so sánh an toàn.
2. Kiểm tra timestamp header; có thể dùng cửa sổ 5 phút nếu đồng hồ server đồng bộ. Mỗi lần gửi có timestamp và chữ ký mới, không kiểm tra độ mới bằng timestamp trong body.
3. Tính HMAC trên body nguyên bản, không parse rồi JSON-encode lại; so sánh chữ ký an toàn.
4. Parse JSON, đối chiếu event ID header với body, environment, metadata.application_id và khách/phiên thuộc hệ thống của bạn.
5. Lưu event bền vững với khóa duy nhất (environment, application_id, event_id). Chỉ trả 2xx khi lưu thành công; xử lý nghiệp vụ trong hàng đợi riêng.

Ví dụ công thức PHP (các biến lấy từ header/body nguyên bản):

$expected = 'v1=' . hash_hmac(
    'sha256',
    $timestampHeader . '.' . $eventIdHeader . '.' . $rawBody,
    $webhookToken
);
$validSignature = hash_equals($expected, $signatureHeader);

Đoạn này chỉ minh họa chữ ký, cần thực hiện đầy đủ các bước kiểm tra và lưu bền vững ở trên. Không ghi token, OTP hoặc toàn bộ dữ liệu tài khoản vào log.

Chống trùng và thứ tự

• Cùng event_id: cùng event được gửi lại; nếu đã lưu thành công, trả 2xx và không chạy nghiệp vụ lần hai.
• Khác event_id nhưng cùng phiên/trạng thái: có thể là các thông báo tương thích cùng mô tả một kết quả. Lọc loại event dùng cho nghiệp vụ như hướng dẫn trên.
• Lưu sequence mới nhất theo phiên hoặc theo tài khoản trong cùng ứng dụng/môi trường. Event cũ vẫn có thể lưu lịch sử nhưng không ghi đè trạng thái mới.
• Không so sánh sequence giữa production và UAT. Dùng API tra kết quả phiên để đối soát khi cần.

Khi nào retry và khi nào dừng?

Khoảng chờ sau mỗi lần thất bại: 1 phút, 2 phút, 5 phút, 10 phút, 30 phút, 60 phút, 120 phút. Mỗi request có timeout tổng 8 giây. HTTP 200 kèm body {"success":false} vẫn được tính thành công: worker không đọc JSON phản hồi.

Nút Gửi lại trong lịch sử sự kiện cho phép gửi lại event failed/skipped sau khi sửa cấu hình; giữ nguyên event ID và đặt lại bộ đếm lần gửi. Cấu hình URL mới không tự phát lại toàn bộ lịch sử skipped.

Hệ thống dùng hàng đợi bền vững và worker chạy liên tục để gửi event mới và retry đến hạn. Không cam kết thời gian giao cố định khi có backlog hoặc endpoint phản hồi chậm. Có thể nhận trùng nếu bên nhận đã lưu nhưng phản hồi bị mất, nên luôn chống trùng.

Kiểm tra với Webhook.site

So sánh event_id trong JSON, không dùng mã request của công cụ. Nhiều request với ID khác nhau có thể là các bước của cùng phiên. Nếu cùng event ID lặp, xem Số lần gửi / HTTP trong lịch sử sự kiện Pay2S. Chỉ gửi thử dữ liệu phù hợp với môi trường thử nghiệm.

Request và response đối chiếu ngày 11/10/2026

Các mẫu dưới đây giữ cấu trúc trường và kiểu dữ liệu. Khóa, chữ ký, URL phiên đã được thay bằng placeholder; danh sách chỉ giữ tối đa hai phần tử và dữ liệu ảnh/PDF/XML dài được rút gọn. Không sao chép placeholder để gọi API thật.

Webhook Hosted Link · Chữ ký & retry

Đối chiếu mã nguồn backend; giá trị minh họa. Payload theo BankHubEvents.php. ACK minh họa từ receiver; webhook có Bearer token và chữ ký HMAC trên raw body.

POST {webhook_url}

Body:

{
  "event_id": "0123456789abcdef0123456789abcdef",
  "version": "1.0",
  "timestamp": 1791691200,
  "environment": "uat",
  "event": "BANK_ACCOUNT_LINKED",
  "metadata": {
    "session_id": "SESSION_ID",
    "application_id": 2,
    "customer_reference": "CUSTOMER_DEMO",
    "bank_code": "ACB",
    "status": "connected",
    "purpose": "LINK_BANK_ACCOUNT",
    "state": "FINISHED_BANK_ACCOUNT_LINK",
    "unlink_mode": "bank",
    "account": {
      "id": 1,
      "bank_code": "ACB",
      "account_number": "P2S99999999",
      "user_bank_id": 1,
      "simulated": 1
    },
    "bank_profile": "acb_personal",
    "account_type": "personal",
    "connection_type": "openapi"
  },
  "sequence": 1
}

HTTP 200. Response:

{
  "success": true
}