Xử lý sự kiện Webhook

Hướng dẫn các bước lập trình một API xử lý sự kiện webhook. Có code mẫu bằng NodeJS

Tích hợp phương pháp webhook rất đơn giản, tất cả mọi thứ bạn cần làm là lập trình một API xử lý sự kiện Webhook. Sau khi bạn đã đăng kí URL của API này vào một mục tích hợp webhook trong Casso.

Mỗi khi Casso phát hiện tài khoản ngân hàng liên kết có một giao dịch mới, Casso sẽ gọi vào API này

Đặc tả của API này là :

Xử lý giao dịch được gửi từ Casso

POST https://websitecuaban.com/api/webhook-event-handler

Headers

Name

Type

Description

secure-token

string

Key bảo mật để xác thực Webhook được gọi từ Casso

Request Body

Name

Type

Description

error

string

Mã lỗi.

data

string

Mảng danh sách các giao dịch mới.

Code

Bạn có thể sử dụng bất kì ngôn ngữ nào hỗ trợ xây dựng restful API để Code.

Quá trình code có thể chỉ mất vài giờ nếu bạn đã quen với việc viết API. Bạn có thể làm theo kịch bản sau:

Tạo dự án Restful API mới (Nodejs Express / Java Spring Boot / PHP single file, ...)
Test in ra được helloword!
Tạo controller mới xử lý một Post tên là /webhook-event-handler
Test : Dùng Curl Post một giao dịch mô phỏng lên /webhook-event-handler và chỉnh code để in ra đúng được nội dung gửi lên (xem thêm phần Test bên dưới)
Rút trích nội dung giao dịch
Xử lý nội dung giao dịch
Phản hồi HTTP status code 200 OK

Ví dụ bên dưới viết bằng NodeJS, log ra số giao dịch Webhook Api nhận dc. Bằng cách chỉnh sửa vài dòng Hello World Sample của Node JS Express

app.js

const express = require('express')
const app = express()
const port = 8080

app.use(express.json());
app.post('/api/webhook-event-handler', (req, res) => {
    let error = req.body.error;
    if (error != 0) {
        //Không làm gì cả.
        return;
    }
    
    //mảng chứa danh sách các giao dịch
    let transactions = req.body.data;
    
    console.log(`Received ${transactions.length} transactions`);
    
    //thêm code xử lý giao dịch ở đây.
    
    res.end("OK");
})

app.listen(port, () => {
  console.log(`Example app listening at http://localhost:${port}`)
})

Bạn có thể xem thêm cách code một API xử lý sự kiện webhook cho tính năng Tích hợp xác nhận thanh toán

Tạo sự kiện webhook để test

Có 5 cách để giả lập giao dịch gửi vào API xử lý webhook bạn đang code như sau:

STT

Môi trường

Phương pháp

Local

Tự gọi API bằng Curl / Postman

Local

Sử dụng ngrok để dẫn (pipe) webhook về local

Dev | Staging

Nút Gọi Thử Trong giao diện setup Webhook

Dev | Staging

Nút đồng bộ giao dịch ngay trong giao diện 1 Tài khoản ngân hàng Demo

Live

Link tài khoản thật & tạo 1 lệnh chuyển tiền

Tuy nhiên, chúng tôi khuyến cáo bạn hãy viết và test thật kĩ trên Local trước , và test nhanh bằng Postman hoặc Curl.

Sử dụng ngrok để public Webhook ở Local

Ngrok là một ứng dụng tạo ra một đường hầm từ máy bạn (desktop, localhost) đi qua hệ thống Firewall/Nat, giúp từ internet có thể truy cập vào máy trạm.

Nếu như bạn đang chạy server ở local port 8080, ở terminal, bạn nhập: ngrok http 8080.

Một url có thể khả dụng trong 8 giờ.

Chỉ sử dụng https://

Bạn có thể sử dụng giao diện web của Ngrok để xêm lưu lượng HTTP request và response qua hệ thống của bạn: http://localhost:8080

Sử dụng Curl để test

Copy nội dung bên dưới, sau khi đã fix lại đường dẫn API xử lý webhook

Mở terminal

curl --location --request POST 'http://localhost:8080/api/webhook-event-handler' \
--header 'secure-token: eogrBiWqaq' \
--header 'Content-Type: application/json' \
--data-raw '{
    "error": 0,
    "data": [
        {
            "id" : 1, 
            "when": "2020-11-02 11:50:30",
            "amount": 200500,
            "description": "DH35",
            "cusum_balance": 15900500,
            "tid": "TF80307914",
            "subAccId": "123456789",
            "bank_sub_acc_id": "123456789",
            "virtualAccount": "",
            "virtualAccountName": "",
            "corresponsiveName": "",
            "corresponsiveAccount": "",
            "corresponsiveBankId": "",
            "corresponsiveBankName": ""
        }
    ]
}'

Paste & Enter

Lưu ý: Trường when có thể có hoặc không có giờ phút giây, tùy thuộc vào ngân hàng.

Ví dụ : ACB thì when sẽ là "2020-11-02", còn vietinbank thì when sẽ là "2020-11-02 11:50:30"

Phát hành

Release dự án lên internet
Cập nhật lại Webhook URL trong cấu hình webhook
Link môt tài khoản ngân hàng thật
Chuyển tiền vào tài khoản ngân hàng (5,000 , 10,000 thôi)
Xác nhận rằng Casso đã gọi qua Webhook và xử lý thành công

Và ... Xin chúc mừng. Bạn đã hoàn tất!!!! Chúng tôi ở đây để làm cho thế giới đơn giản hơn. ^^

PreviousThiết lập Webhook thủ công NextChứng thực API

Last updated 1 year ago