Webhook¶

Cảnh báo

Rất được khuyến nghị tham khảo ý kiến của một nhà phát triển, kiến trúc sư giải pháp, hoặc vai trò kỹ thuật khác khi quyết định sử dụng webhooks và trong suốt quá trình triển khai. Nếu không được cấu hình đúng, webhooks có thể gây gián đoạn cơ sở dữ liệu Odoo và có thể mất thời gian để khôi phục.

Webhooks, có thể được tạo trong Odoo Studio, cho phép bạn tự động hoá một hành động trong cơ sở dữ liệu Odoo của mình khi một sự kiện cụ thể xảy ra trong một hệ thống bên ngoài khác.

Thực tế, cách hoạt động như sau: khi sự kiện xảy ra trong hệ thống bên ngoài, một tệp dữ liệu (gọi là "payload") được gửi tới URL webhook của Odoo thông qua yêu cầu API POST, và một hành động được định nghĩa trước sẽ được thực thi trong cơ sở dữ liệu Odoo của bạn.

Khác với hành động lên lịch, chạy ở các khoảng thời gian đã định, hoặc các yêu cầu API thủ công, cần được gọi một cách rõ ràng, webhook cho phép giao tiếp và tự động hóa theo thời gian thực, dựa trên sự kiện. Ví dụ, bạn có thể thiết lập một webhook để dữ liệu tồn kho Odoo của bạn được cập nhật tự động khi đơn bán hàng được xác nhận trong hệ thống điểm bán hàng bên ngoài.

Việc thiết lập webhook trong Odoo không cần viết mã khi kết nối hai cơ sở dữ liệu Odoo, nhưng testing a webhook yêu cầu một công cụ bên ngoài. Custom target records or actions có thể đòi hỏi kỹ năng lập trình.

Ghi chú

Bài viết này giới thiệu cách tạo webhook nhận dữ liệu từ nguồn bên ngoài. Tuy nhiên, cũng có thể tạo một hành động tự động mà sends data to an external webhook khi có sự thay đổi trong cơ sở dữ liệu Odoo của bạn.

Tạo webhook trong Odoo¶

Quan trọng

Trước khi triển khai webhook trong cơ sở dữ liệu thực, hãy cấu hình và kiểm tra nó bằng cách sử dụng một để đảm bảo webhook hoạt động như mong muốn.

Mẹo

Activating developer mode trước khi tạo webhook sẽ mang lại sự linh hoạt hơn trong việc chọn model mà quy tắc tự động hướng tới. Nó cũng cho phép bạn tìm tên kỹ thuật của mô hình và các trường, có thể cần để cấu hình payload.

Để tìm tên kỹ thuật của một mô hình, khi chế độ nhà phát triển đã bật, di chuột lên tên mô hình rồi nhấp vào (Internal link). Tên kỹ thuật có thể được tìm thấy trong trường Model. Ví dụ, webhook đơn bán hàng sử dụng mô hình Đơn bán hàng, nhưng tên kỹ thuật sale.order được dùng trong payload.

Để tạo webhook trong Studio, làm theo các bước sau:

Open Studio và nhấp vào Webhooks, sau đó Mới
Đặt tên webhook một cách rõ ràng, có ý nghĩa để nhận diện mục đích của nó.
Nếu cần và chế độ nhà phát triển đã được kích hoạt, chọn Model phù hợp từ danh sách thả xuống. Nếu chế độ nhà phát triển chưa được kích hoạt, quy tắc tự động sẽ mặc định áp dụng vào mô hình hiện tại.
URL của webhook được tự động tạo, nhưng có thể thay đổi nếu cần bằng cách nhấp vào Rotate Secret. Đây là URL nên được sử dụng khi triển khai webhook trong hệ thống bên ngoài sẽ gửi cập nhật tới cơ sở dữ liệu.

Cảnh báo
URL là bảo mật và nên được xử lý cẩn thận. Chia sẻ nó trực tuyến hoặc mà không thận trọng có thể cung cấp quyền truy cập không mong muốn vào cơ sở dữ liệu Odoo. Nếu URL được cập nhật sau khi triển khai ban đầu, hãy chắc chắn cập nhật nó trong hệ thống bên ngoài.
Nếu muốn, bật Ghi lại cuộc gọi để theo dõi lịch sử các yêu cầu API được gửi tới URL của webhook, ví dụ, để mục đích khắc phục sự cố.
Nếu hệ thống gửi webhook không phải là Odoo, hãy điều chỉnh mã Target Record để tìm trường ghi JSON được bao gồm trong payload khi yêu cầu API được gửi tới URL của webhook. Nếu hệ thống gửi webhook là cơ sở dữ liệu Odoo, hãy đảm bảo rằng id và model xuất hiện trong payload.

Nếu webhook được dùng để tạo bản ghi trong cơ sở dữ liệu Odoo, hãy sử dụng model.browse(i) hoặc model.search(i) thay vì định dạng mặc định Target Record.
Nhấp vào Add an action trong tab Actions To Do để xác định actions sẽ được thực thi.
Trước khi triển khai webhook trong hệ thống bên ngoài, kiểm tra nó để đảm bảo nó hoạt động như dự định.

Mẹo

Webhooks cũng có thể được tạo qua menu Automations trong Studio bằng cách chọn trigger On webhook.
Để truy cập lịch sử các yêu cầu API nếu Log Calls đã được bật, nhấn nút thông minh Logs ở trên cùng của biểu mẫu Automation rules.
Nếu mục đích của webhook là bất kỳ điều gì khác ngoài việc cập nhật một bản ghi hiện có, ví dụ, tạo một bản ghi mới, thì hành động Execute Code phải được chọn.

Kiểm tra webhook¶

Kiểm tra webhook đòi hỏi một payload thử nghiệm và một công cụ hoặc hệ thống bên ngoài, như Postman, để gửi payload qua yêu cầu POST API. Phần này trình bày các bước để kiểm thử webhook trong Postman.

Mẹo

Xem phần webhook use cases section để có hướng dẫn chi tiết từng bước về cách kiểm tra webhook bằng payload thử nghiệm.
Để nhận được hỗ trợ cụ thể trong việc kiểm tra webhook với Postman, hãy liên hệ với đội hỗ trợ của họ.

Trong Postman, tạo một yêu cầu HTTP mới và đặt phương thức của nó thành POST.
Sao chép URL webhook từ cơ sở dữ liệu Odoo của bạn bằng biểu tượng (link) và dán vào trường URL trong Postman.
Nhấn vào tab Body và chọn raw.
Đặt loại tệp thành JSON, sau đó sao chép mã từ payload kiểm tra và dán vào trình chỉnh sửa mã.
Nhấn Send.

Trong trình xem Response ở phía dưới màn hình trong Postman, các chi tiết, bao gồm mã phản hồi HTTP, cho biết webhook có hoạt động đúng hay không.

Một thông điệp 200 OK hoặc status: ok cho biết webhook đang hoạt động bình thường ở phía Odoo. Từ đây, việc triển khai có thể bắt đầu với hệ thống khác để tự động gửi các yêu cầu API tới URL webhook của Odoo.
Nếu có bất kỳ phản hồi nào khác được trả về, số liên quan đến nó sẽ giúp xác định vấn đề. Ví dụ, thông báo 500 Internal Server Error có nghĩa là Odoo không thể diễn giải cuộc gọi một cách chính xác. Trong trường hợp này, hãy đảm bảo các trường được tìm thấy trong tệp JSON được ánh xạ chính xác trong cấu hình webhook và trong hệ thống gửi cuộc gọi thử.

Mẹo

Bật call logging trong cấu hình webhook của Odoo sẽ cung cấp nhật ký lỗi nếu webhook không hoạt động như mong đợi.

Triển khai webhook trong hệ thống bên ngoài¶

Khi webhook đã được tạo thành công trong Odoo và đã thử nghiệm, hãy triển khai nó trong hệ thống gửi dữ liệu tới cơ sở dữ liệu Odoo, đảm bảo các yêu cầu API POST được gửi tới URL của webhook.

Các trường hợp sử dụng Webhook¶

Dưới đây là hai ví dụ về cách sử dụng webhook trong Odoo. Một payload thử nghiệm được cung cấp cho mỗi ví dụ, và có thể tìm thấy trong phần thử nghiệm webhook. Postman được sử dụng để gửi payload thử nghiệm.

Cập nhật tiền tệ của đơn bán hàng¶

Webhook này cập nhật một đơn bán hàng trong ứng dụng Sales sang USD khi hệ thống bên ngoài gửi một yêu cầu POST API tới URL của webhook, trong đó bao gồm số đơn bán hàng đó (được xác định bởi trường id của payload).

Có thể hữu ích cho các công ty con ở bên ngoài Hoa Kỳ có công ty mẹ đặt tại Hoa Kỳ hoặc trong trường hợp sáp nhập khi hợp nhất dữ liệu vào một cơ sở dữ liệu Odoo duy nhất.

Tạo webhook¶

Để tạo webhook này, thực hiện các bước sau:

Mở ứng dụng Sales, sau đó mở Studio và nhấp vào Webhooks. Mô hình Sales Order được chọn mặc định.
Nhấp vào New. Trigger được đặt thành On webhook theo mặc định.
Đặt Bản ghi mục tiêu thành model.env[payload.get('_model')].browse(int(payload.get('_id'))), trong đó:
- payload.get('_model') lấy giá trị liên kết với khóa model trong payload, tức là sale.order, là tên kỹ thuật của mô hình Sales Order.
- payload.get('_id') lấy giá trị liên kết với khóa id trong payload, tức là số của đơn bán hàng mục tiêu trong cơ sở dữ liệu Odoo của bạn, sau khi bỏ ký tự S và các số 0 đầu.
- int chuyển đổi id đã lấy thành một số nguyên (tức là một số nguyên đầy đủ) vì phương thức browse() chỉ có thể được sử dụng với một số nguyên.
Nhấn vào Thêm một hành động.
Trong phần Type, nhấp vào Update Record.
Trong phần Action details, chọn Update, chọn trường Currency, và chọn USD.
Nhấn Save & Close.

Kiểm tra webhook¶

Để kiểm tra webhook này, thực hiện như sau:

Khi mở Postman, tạo một yêu cầu HTTP mới và đặt phương thức của nó thành POST.
Sao chép URL của webhook Odoo bằng biểu tượng (link) và dán vào trường URL trong Postman.
Nhấn vào tab Body và chọn raw.
Đặt loại tệp thành JSON, sau đó sao chép đoạn mã này, tức là payload, và dán nó vào trình chỉnh sửa mã:
```
{
    "_model": "sale.order",
    "_id": "SALES ORDER NUMBER"
}
```
Trong cơ sở dữ liệu Odoo của bạn, chọn một đơn bán hàng để kiểm tra webhook. Trong mã đã dán, thay thế SALES ORDER NUMBER bằng số của đơn bán hàng mà không có ký tự S hay các số 0 phía trước số. Ví dụ, một đơn bán hàng có số S00007 nên được nhập là 7 trong Postman.
Nhấn Send.
Tham khảo Response viewer trong Postman để xác định webhook có hoạt động đúng hay không. Nếu một tin nhắn khác với 200 OK hoặc status: ok được trả về, số liên quan đến tin nhắn đó sẽ giúp xác định vấn đề.

Tạo một liên hệ mới¶

Webhook này sử dụng mã tuỳ chỉnh để tạo một liên hệ mới trong cơ sở dữ liệu Odoo khi hệ thống bên ngoài gửi một yêu cầu POST API đến URL của webhook chứa thông tin của liên hệ. Điều này có thể hữu ích cho việc tự động tạo nhà cung cấp hoặc khách hàng mới.

Tạo webhook¶

Để tạo webhook này, thực hiện các bước sau:

Mở ứng dụng Contacts, sau đó mở Studio và nhấp vào Webhooks. Mô hình Contact được chọn mặc định.
Nhấp vào New. Trigger được đặt thành On webhook theo mặc định.
Đặt Target Record thành model.browse([2]). Về cơ bản, đây là một trình giữ chỗ vì mã trong hành động tự động sẽ cho webhook biết những gì cần lấy từ payload và trong mô hình nào cần tạo bản ghi.
Nhấn vào Thêm một hành động.
Trong phần Type, nhấp vào Execute Code

Sao chép đoạn mã này và dán vào trình chỉnh sửa mã trong tab Code của phần Action details:

# variables to retrieve and hold data from the payload
contact_name = payload.get('name')
contact_email = payload.get('email')
contact_phone = payload.get('phone')

# a Python function to turn the variables into a contact in Odoo
if contact_name and contact_email:
    new_partner = env['res.partner'].create({
        'name': contact_name,
        'email': contact_email,
        'phone': contact_phone,
        'company_type':'person',
        'customer_rank': 1,
    })
# an error message for missing required data in the payload
else:
    raise ValueError("Missing required fields: 'name' and 'email'")

Nhấn Save & Close.

Kiểm tra webhook¶

Để kiểm tra webhook này, thực hiện như sau:

Trong Postman, tạo một yêu cầu HTTP mới và đặt phương thức của nó thành POST.
Sao chép URL của webhook Odoo bằng biểu tượng (link) và dán vào trường URL trong Postman.
Nhấn vào tab Body và chọn raw.
Đặt loại tệp thành JSON, sau đó sao chép đoạn mã này, tức là payload, và dán nó vào trình chỉnh sửa mã:
```
{
    "name": "CONTACT NAME",
    "email": "CONTACTEMAIL@EMAIL.COM",
    "phone": "CONTACT PHONE NUMBER"
}
```
Trong mã đã dán, hãy thay thế CONTACT NAME, CONTACTEMAIL@EMAIL.COM và CONTACT PHONE NUMBER bằng thông tin của liên hệ mới.
Nhấn Send.
Tham khảo Response viewer trong Postman để xác định webhook có hoạt động đúng hay không. Nếu một tin nhắn khác với 200 OK hoặc status: ok được trả về, số liên quan đến tin nhắn đó sẽ giúp xác định vấn đề.