Thiết lập Webhook thủ công

Mô hình hoạt động

Casso sử dụng webhook để thông báo cho ứng dụng của bạn khi có một giao dịch tiền vào hoặc tiền ra tài khoản ngân hàng của bạn.

Tích hợp Casso vào ứng dụng của bạn bằng webhook chỉ bao gồm 3 bước đơn giản

1. Lập trình một webhook endpoint để xử lý sự kiện webhook trên server của bạn

2. Giả lập giao dịch mới từ ngân hàng để Test và đảm bảo webhook endpoint của bạn chạy đúng.

3. Đăng kí URL của Webhook endpoint vào Casso và Go live.

Trước khi bắt đầu

Bạn cần phải:

• Tạo một tài khoản tại Casso

• Liên kết một tài khoản ngân hàng vào Casso. Xem thêm Tài khoản ngân hàng test

Thiết lập webhook trong Casso

Đăng nhập vào tài khoản tại casso.vn

Truy cập vào Kết nối > Tích hợp và ấn vào nút Thêm tích hợp

Trong danh sách Chọn ứng dụng để tích hợp , chọn Webhook hoặc Webhook V2. Sẽ mở ra giao diện Thêm tích hợp Webhook:

Ở mục 1. Chọn ngân hàng :

• Bạn chọn tài khoản ngân hàng sẽ được theo dõi để bắn thông tin giao dịch.

• Bạn có thể chọn Tất cả để Hệ thống Casso bắn giao dịch của tất cả các tài khoản ngân hàng đã liên kết.

Bạn nhấn nút Tiếp tục để chuyển sang bước Thiết lập Webhook nhận dữ liệu:

Webhook V2

Webhook

Ở bước Thiết lập :

• Thông số Webhook URL sẽ là đường dẫn tới API endpoint của hệ thống xử lý sự kiện webhook trên web server của bạn.

• Thông số Key bảo mật là một chuỗi các ký tự ngẫu nhiên do Casso tự sinh ra cho mỗi tích hợp. Key bảo mật này sẽ dùng để tạo chữ ký số đối với dữ liệu của Webhook và một số thông tin khác. Bạn có thể kiểm tra header lấy thông tin chữ ký số để xác thực việc gọi vào Webhook URL là hợp lệ.

• Nếu bạn cảm thấy Key bảo mật hiện tại không an toàn, bạn có thể nhấn nút rotate ở bên phải trường Key bảo mật để làm mới và Lưu lại tích hợp.

• Tuy nhiên, hãy đảm bảo rằng tất cả sự kiện của Tích hợp Webhook V2 đã được xử lý thành công trước khi làm mới Key bảo mật. Nếu bạn làm mới Key bảo mật trong khi vẫn còn sự kiện chưa được xử lý, các sự kiện này vẫn sẽ dùng Key bảo mật cũ tạo chữ ký số.

Ở bước Thiết lập :

• Thông số Webhook URL sẽ là đường dẫn tới API endpoint của hệ thống xử lý sự kiện webhook trên web server của bạn.

• Thông số Key bảo mật chứa một mã bí mật mà mỗi lần gọi vào Webhook URL, Casso sẽ đính kèm key bảo mật này vào trong HTTP Header. Bạn có thể kiểm tra header lấy thông tin mã bí mật để xác thực việc gọi vào Webhook URL là hợp lệ.

Ở bước Cấu hình dữ liệu, bạn cần thiết lập các tùy chọn Gửi kèm thông tin số dư, Gửi kèm thông tin mã giao dịch, Strict mode để Casso có thể gửi đầy đủ thông tin mà bạn cần qua webhook đồng thời xử lý phản hồi từ hệ thống của bạn một cách chính xác.

Bấm vào nút Tiếp tục để tới bước tiếp theo.

Bấm vào nút Gọi thử, để hệ thống Casso bắn một giao dịch test vào Webhook URL.

Nếu Casso bắn Webhook URL thành công, tức là cấu hình của bạn đã hợp lệ. Lúc này bạn có thể bấm vào nút Lưu để hệ thống lưu lại cấu hình này.

Yêu cầu của Webhook URL

Casso sẽ thực hiện việc gọi API vào Webhook URL mỗi khi có giao dịch mới. Webhook URL sẽ cần phải đáp ứng các yêu cầu sau:

Khả năng truy cập

• Phải là đường dẫn công khai có thể truy cập từ internet

• Đường dẫn sử dụng giao thức bảo mật HTTPS

• Nếu website sử dụng Cloudflare hoặc các dịch vụ ngăn chặn DDOS, lưu ý bạn phải whitelist IP của Casso.

Phản hồi khi thành công

Sau khi xử lý, webhook của bạn phải phản hồi với status code là 200 OK. Và đáp ứng thời gian phản hồi dưới 5 giây ( Casso sẽ thiết lập timeout cho request POST bắn webhook là 5s)

Xử lý các trường hợp thất bại.

Nếu quá trình bắn webhook thất bại vì một lý do nào đó, Casso sẽ gọi lại liên tục webhook trong 24 giờ sau đó, lần đầu gọi sẽ sau 1 phút và thời gian chờ này sẽ tăng lên thành giá trị Fibonacci kế tiếp sau mỗi lần gọi lại thất bại.

Tổng cộng, Casso sẽ gọi lại 1 sự kiện webhook nhiều nhất là 17 lần. Sau đó mới bỏ qua và chuyển sự kiện webhook qua trạng thái Thất Bại (FAIL).

Sau 24 giờ liên tục gọi webhook toàn thất bại, Casso sẽ chuyển cấu hình webhook sang trạng thái Tạm Dừng (PAUSED). Khi cấu hình webhook bị tạm dừng mà có giao dịch mới phát sinh, các sự kiện webhook này sẽ không được thực hiện mà được lưu lại với trạng thái là Tạm Giữ (HOLDING). Khách hàng sau khi fix lỗi của hệ thống xử lý sự kiện webhook thì có thể truy cập vào giao diện Casso để thực hiện lại (Replay) các sự kiện webhook này.

Sau 7 ngày cấu hình webhook bị tạm dừng mà không được xử lý, Casso sẽ chuyển cấu hình webhook sáng trạng thái Tắt (DISABLE). Các giao dịch xảy ra khi cấu hình webhook bị tắt sẽ không có khả năng thực hiện lại.

Chống trùng lắp

Để chống lại phương pháp tấn công Replay Attack, Hệ thống xử lý sự kiện Webhook của bạn cần phải được xử lý chống trùng lặp thông qua kiểm tra xem một giao dịch mới đã được xử lý trước đây hay chưa? Mỗi giao dịch của Casso được định danh bởi một id. Với một webhook mới đến, bạn hãy kiểm tra xem id của giao dịch này đã được xử lý trước đây hay chưa, nếu đã có thì tức là giao dịch này đã bị Replay bởi một lý do nào đó, hãy bỏ qua nó.

Xử lý hậu kiểm

Dù tỉ lệ có thể sẽ rất thấp, nhưng sẽ luôn có khả năng webhook thất bại, để tránh trường hợp bị sót giao dịch. Nhà phát triển có thể cân nhắc cung cấp tính năng Tra soát toàn bộ giao dịch bắng cách sử dụng API để tải về các giao dịch và kiểm tra xem có giao dịch nào sót không. Xem thêm ở mục Tạo Auth code thủ công.

Cấu trúc dữ liệu gửi qua Webhook

Casso sẽ bắn dữ liệu vào Webhook URL mà bạn đã khai báo, Dữ liệu định dạng JSON, trong đó trường data sẽ lưu thông tin giao dịch mới.

{
    "error": 0,
    "data": {
        "id": 0, // Mã định danh duy nhất của giao dịch (Casso quy định)
        "reference": "BANK_REF_ID", // Mã giao dịch từ phía ngân hàng
        "description": "giao dich thu nghiem",  // Nội dung giao dịch
        "amount": 599000, // Số tiền giao dịch
        "runningBalance": 25000000, // Số dư sau giao dịch
        "transactionDateTime": "2025-02-12 15:36:21", // Thời gian giao dịch
        "accountNumber": "88888888", // Số tài khoản mà giao dịch thuộc về
        "bankName": "VPBank", // Tên ngân hàng
        "bankAbbreviation": "VPB", // Viết tắt tên ngân hàng
        "virtualAccountNumber": "", // Tài khoản ảo
        "virtualAccountName": "", // Tên tài khoản ảo
        "counterAccountName": "", // Tên tài khoản đối ứng
        "counterAccountNumber": "", // Tài khoản đối ứng
        "counterAccountBankId": "", // Mã ngân hàng đối ứng
        "counterAccountBankName": "" // Tên ngân hàng đối ứng
    }
}

{
    "error": 0,
    "data": [
        {
            "id": 6785,        // Mã định danh duy nhất của giao dịch (Casso quy định)
            "tid": "BANK_REF_ID", // Mã giao dịch từ phía ngân hàng
            "description": "giao dich thu nghiem", // Nội dung giao dịch
            "amount": 79000, // Số tiền giao dịch
            "cusum_balance": 20079000,  // Số tiền còn lại sau giao dịch                 
            "when": "2020-10-14 00:34:57",    // Thời gian ghi có giao dịch ở ngân hàng
            "bank_sub_acc_id": "123456789",   // Mã tài khoản ngân hàng mà giao dịch thuộc về
            "subAccId" :  "123456789"       // Tương tự field bank_sub_acc_id, nhằm tương thích với code cũ
            "bankName" : "VPBank", // Tên ngân hàng
            "bankAbbreviation" : "VPB", // Viết tắt tên ngân hàng 
            "virtualAccount": "", // Tài khoản ảo
            "virtualAccountName": "", // Tên tài khoản ảo
            "corresponsiveName": "", // Tên tài khoản đối ứng
            "corresponsiveAccount": "", // Tài khoản đối ứng
            "corresponsiveBankId": "", // Mã ngân hàng đối ứng
            "corresponsiveBankName": "" // Tên ngân hàng đối ứng
        },
    
    ]
}

Lập trình webhook

Một số tài nguyên ban có thể tham khảo để lập trình Module xử lý webhook Webhook Event Handler.

Hãy bắt đầu