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

Casso cho phép tích hợp với một Webhook API gọi tới server của bạn. Mỗi khi có giao dịch mới, Casso sẽ thực hiện gọi tới API bạn đã thiết lập sẵn để gửi thông tin giao dịch này.

Mô hình hoạt động

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 Thiết lập > Tích hợp và ấn vào nút Thêm tích hợp

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

Ở mục Ngân hàng nhận webhook :

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ước Nhập thông tin Webhook :

Thông số Webhook URL sẽ là đường dẫn tới API đầu nhậ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ệ.

Không sử dụng Webhook URL là đường dẫn chỉ có thể truy cập tư mạng nội bộ hoặc localhost, 127.0.01, 192.160.1.x ... Webhook URL buộc phải là một đường dẫn public trên Internet.

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.

Strict mode: là bước kiểm tra nâng cao, khi phản hồi về status 200, thì Casso sẽ kiểm tra thêm 1 bước nữa trong JSON trả về success : 1 hoặc success: true. Nếu là 0 thì hệ thống sẽ hiểu là fail và Casso sẽ gửi lại webhook. Nếu không bật strict mode thì khi nhận phản hồi status 200 thì Casso sẽ lưu lại là đã gửi webhook thành công.

MẸO : Trong quá trình lập trình tích hợp, bên cạnh Webhook tùy chỉnh trỏ tới website của bạn, bạn có thể đăng kí thêm 1 webhook tùy chỉnh khác sử dụng các dịch vụ như pipedream.com, webhook.site, ngrok.com để debug nội dung Casso gửi vào Webhook URL

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 Cloudfare 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 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 12 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 thử lại thất bại.

Chống trùng lắp

Để chống lại phương pháp tấn công Replay Attack, 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 hoặc OAuth 2

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 một mảng các giao dịch mới.

{
    "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ề
        },
    
    ]
}