Kết nối webhook

- Webhook là cấu hình chức năng tự động đồng bộ dữ liệu từ một sự kiện nhất định. Bạn phải đăng ký một URL https:// trong đó dữ liệu sự kiện được lưu trữ ở định dạng JSON.

Các mục liên quan

Bước 1: Tạo app

- Vào link https://developers.haravan.com/apps
(nếu chưa đăng nhập trước đó thì hệ thống sẽ chuyển sang page login https://accounts.haravan.com, tại page này bạn có thể đăng nhập hoặc click tạo mới tài khoản.)

Tạo App

- Sau khi đăng nhập/đăng ký thành công hệ thống sẽ hiển thị ra màn hình listing các ứng dụng đã tạo, Click “Create App” để tạo ứng dụng mới.

Tạo App

- Giao diện tạo mới ứng dụng.

Giao diện tạo mới ứng dụng

  • Name: Tên ứng dụng.
  • Description: Mô tả ứng dụng.
  • Redirect Url: Đường dẫn ứng dụng của bạn, khi click vào ứng dụng hệ thống sẽ gọi tới.

- Tạo ứng dụng thành công.

Các field cần lưu lại vào config để sử dụng: App Id, App Secret, Redirect Url

Tạo ứng dụng thành công.

- Sau khi tạo thành công , app sẽ có trên danh sách https://developers.haravan.com/apps

Sau khi tạo thành công

Bước 2: Tạo ngrok để đăng kí webhook

- Ngrok (https://ngrok.com/) là tool giúp bạn test webhook, nếu bạn chưa có tên miền online.

- Ngrok sẽ tạo ra cổng kết nối từ public internet đến port máy tính local của bạn.

- Sau khi tải ngrok về , chạy file ngrok.exe.

- Chạy lệnh ngrok http 3000 (port tùy ý, ví dụ ở đây là port 3000)

Lưu ý:

  • 1 tên miền ngrok có thể tồn 8h, sau đó phải chạy lệnh lại để lấy tên miên mới
  • Và tên miền để đăng kí webhook bắt buộc phải là https://

Tạo ngrok để đăng kí webhook

Bước 3: Đăng kí webhook

- Vào mục Webhooks, chọn nút Register để đăng kí Webhooks.

Cấu hình webhook

- Điền vào CallBack URL và Verify Token :

  • Nhập vào CallBack URL : là đường dẫn webhook dùng để gọi về app và bắn dữ liệu về app. Đảm bảo url đã cấu hình trên app để có thể nhận webhook
  • Nhập vào Verify Token : là một chuỗi random bất kì tối thiểu 1 kí tự, vì dùng để chứng thực với app nên cần đảm bảo giống với chuỗi đã cấu hình trên app.

Nhập vào Verify Token

- Khi nhấn submit, webhook sẽ gọi đến app theo đường dẫn Callback URL

- Khi gọi đến app thành công, webhook sẽ gửi 1 object vào app để kiểm tra

{
  "hub.mode": "subscribe",
  "hub.verify_token": "YiquHMHXpfRMkgNTUc60kFaLLKYpDGR9",
  "hub.challenge": "23236cb70fe64c1ebcf047574a41eb14"
}

- Khi nhận được objet , chúng ta cần kiểm tra xem hub.verify_tokenverify_token trong app có giống nhau không.

  • Nếu giống nhau, response ngược lại với status 200 kèm theo giá trị của hub.challenge.
  • Nếu không giống, response ngược lại với status 401.

- Khi đăng kí thành công, reload lại page để thấy những mục có thể Subscribe để được webhook trả về app.

Đăng kí thành công

- Sau khi đăng kí webhook thành công bằng ngrok , bạn có thể vào đường dẫn http://localhost:4040 để kiểm tra những gì webhook trả về.

 Webhook register

Bước 4: Gọi api subscribe webhook cho app

- Đây là bước đăng kí webhook để app có thể nhận dữ liệu từ webhook, bước này sẽ thực hiện sau khi cài app vì cần có access_token để subscribe. (tham khảo hướng dẫn tạo app và kết nối api)

Lưu ý:

  • Ta cần thêm scope sử dụng webhook khi cần app: wh_api
  • Tham khảo thêm ở hướng dẫn cài app và hướng dẫn scope

- Dùng access_token có dược để subscribe webhook cho app bằng cách gọi api.

4.1. Request

Method

URL  

POST

https://webhook.haravan.com/api/subscribe

Header:  
   Content-Type: application/json
   Authorization: Bearer + access_token 

4.2. Response

Status

Response

200

{
"error": false,
"message": "Đăng ký webhook thành công."
}

422

{"error": "Unprocessable Entity"}

401

Unauthorized

429

Too many requests

500

Something went wrong. Please try again later.

4.3. Sử dụng Postman

Sử dụng Postman

Bước 5: Nhận dữ liệu từ Webhook

- Sau khi register và subscribe cho app thì webhook sẽ bắn dữ liệu tương ứng với các mục mà bạn đã subscribe trên developers qua callback url với method là POST đến app.

- Khi bắn dữ liệu, webhook sẽ kèm theo nhiều thông tin, trong đó sẽ có

  • Org_id
  • Topic : tùy theo mỗi chỉ mục mà topic sẽ khác.

- Ví dụ ở đây subscribe Cập nhật tài khoản.

Webhook thường

- Khi bạn cập nhật tài khoản ở https://accounts.haravan.com/, webhook sẽ gửi dữ liệu đã cập nhật của tài khoản về app với topic là “user/update” về lại callback url mà bạn đã khai báo với method là POST.

 Webhook thường

 Webhook thường

Bước 6: Chứng thực Webhook

- Khi nhận được thông tin gửi về từ webhook, bạn cần chứng thực xem đó có phải là thông tin được gửi về từ hệ thống hay không.

  • Đầu tiên cần lấy App Secret trong mục Settings.

 Webhook thường

  • Để xác thực webook, ta sử dùng hàm băm HMAC với thuật toán “sha1” để mã hóa (data trả về webhook + App Secret) ra được mã hash, sau đó lấy mã hash mã hóa hex lần nữa ra được kết quả, xong rồi lấy kết quả mới có được đem đi so sanh với header  X-Haravan-Hmac-SHA256 mà webhook trả về cho mình.
  • Ví dụ code PHP:

    <?php
    define('Haravan_APP_SECRET','my_shared_secret');
    
    function verify_webhook($data,$hmac_header) { $calculated_hmac = hex_encode(hash_hmac('sha1', $data, Haravan_APP_SECRET, true)); return ($hmac_header == $calculated_hmac); }
    $hmac_header = $_SERVER['X-Haravan-Hmac-Sha256']; $data = file_get_contents('php://input'); $verified = verify_webhook($data, $hmac_header); error_log('Webhook verified:'.var_export($verified, true)); //check error.log to see the result ?>
  • Nếu xác thực thành công, app nhận dữ liệu, response về cho webhook status 200.

Những lưu ý

  • Khi nhận webhook nhớ reponse về status 200 nếu không webhook sẽ auto retry bắn lại.
  • Tháo ngrok ra nếu không dùng nữa để tránh spam hệ thống.
  • Khi xóa app thì sẽ mất subscribe, khi cài lại app cần chạy lại subscribe cho app.