เว็บฮุค¶

Warning

It is highly recommended to consult with a developer, solution architect, or another technical role when deciding to use webhooks and throughout the implementation process. If not properly configured, webhooks may disrupt the NightPOS database and can take time to revert.

Webhooks, which can be created in NightPOS Studio, allow you to automate an action in your NightPOS database when a specific event occurs in another, external system.

In practice, this works as follows: when the event occurs in the external system, a data file (the "payload") is sent to the NightPOS webhook's URL via a POST API request, and a predefined action is performed in your NightPOS database.

Unlike scheduled actions, which run at predefined intervals, or manual API requests, which need to be explicitly invoked, webhooks enable real-time, event-driven communication and automation. For example, you can set up a webhook to have your NightPOS inventory data updated automatically when a sales order is confirmed in an external point-of-sale system.

Setting up a webhook in NightPOS requires no coding when connecting two NightPOS databases, but testing a webhook requires an external tool. Custom target records or actions may require programming skills.

Note

This article covers creating a webhook that receives data from an external source. However, it is also possible to create an automated action that sends data to an external webhook when a change occurs in your NightPOS database.

Create a webhook in NightPOS¶

Important

Before implementing a webhook in a live database, configure and test it using a duplicate database to ensure the webhook performs as intended.

Tip

:ref:`การเปิดใช้งานโหมดนักพัฒนา <developer-mode>`ก่อนสร้างเว็บฮุกจะให้ความยืดหยุ่นมากขึ้นในการเลือก:doc:`โมเดล <../models_modules_apps>`ที่กฎระบบอัตโนมัติกำหนดเป้าหมาย นอกจากนี้ยังช่วยให้คุณค้นหาชื่อทางเทคนิคของโมเดลและฟิลด์ ซึ่งอาจจำเป็นในการกำหนดค่าเพย์โหลด

เพื่อค้นหาชื่อทางเทคนิคของโมเดล เมื่อเปิดใช้งานโหมดนักพัฒนาแล้ว ให้เลื่อนเมาส์ไปที่ชื่อโมเดล จากนั้นคลิก (ลิงก์ภายใน) ชื่อทางเทคนิคสามารถพบได้ในฟิลด์ โมเดล ตัวอย่างเช่น เว็บฮุกคำสั่งขายใช้โมเดล คำสั่งขาย แต่ชื่อทางเทคนิค sale.order ใช้ในเพย์โหลด

เพื่อสร้างเว็บฮุกใน สตูดิโอ ดำเนินการดังนี้:

เปิดสตูดิโอ และคลิก เว็บฮุก จากนั้นคลิก สร้างใหม่
ตั้งชื่อเว็บฮุคที่ชัดเจนและมีความหมาย เพื่อระบุวัตถุประสงค์ของเว็บฮุค
หากจำเป็น และเปิดใช้งานโหมดผู้พัฒนาแล้ว ให้เลือก:guilabel:`โมเดล`ที่เหมาะสมจากรายการแบบเลื่อนลง หากไม่ได้เปิดใช้งานโหมดผู้พัฒนา กฎการทำงานอัตโนมัติจะกำหนดเป้าหมายเป็นโมเดลปัจจุบันโดยค่าเริ่มต้น
URL ของเว็บฮุคจะถูกสร้างขึ้นโดยอัตโนมัติ แต่สามารถเปลี่ยนแปลงได้หากจำเป็นโดยคลิก:guilabel:หมุนเปลี่ยนรหัสลับ นี่คือ URL ที่ควรใช้เมื่อใช้งานเว็บฮุคในระบบภายนอกที่จะส่งการอัปเดตไปยังฐานข้อมูล

Warning
The URL is confidential and should be treated with care. Sharing it online or without caution can provide unintended access to the NightPOS database. If the URL is updated after the initial implementation, make sure to update it in the external system.
หากต้องการ ให้เปิดใช้งาน:guilabel:`บันทึกการเรียก`เพื่อติดตามประวัติคำขอ API ที่ทำกับ URL ของเว็บฮุค เช่น เพื่อวัตถุประสงค์ในการแก้ไขปัญหา
If the system sending the webhook is not NightPOS, adjust the Target Record code to look for the JSON record included in the payload when the API request is made to the webhook's URL. If the system sending the webhook is an NightPOS database, ensure that the id and model appear in the payload.

If the webhook is used to create records in the NightPOS database, use model.browse(i) or model.search(i) instead of the default Target Record format.
คลิก:guilabel:`เพิ่มการดำเนินการ`ในแท็บ:guilabel:`การดำเนินการที่ต้องทำ`เพื่อกำหนด:ref:`การดำเนินการ <studio/automated-actions/action>`ที่จะดำเนินการ
ก่อนใช้งานเว็บฮุคในระบบภายนอก ให้:ref:`ทดสอบ <studio/webhooks/test-webhook>`เพื่อให้แน่ใจว่าทำงานตามที่ตั้งใจไว้

Tip

สามารถสร้างเว็บฮุคได้ผ่านเมนู:guilabel:ระบบอัตโนมัติ`ใน**สตูดิโอ**โดยเลือกตัวกระตุ้น:guilabel:`บนเว็บฮุค
เพื่อเข้าถึงประวัติคำขอ API หากเปิดใช้งาน:guilabel:บันทึกการเรียก`แล้ว ให้คลิกปุ่มสมาร์ท:guilabel:`ล็อก`ที่ด้านบนของแบบฟอร์ม:guilabel:`กฎการทำงานอัตโนมัติ
หากวัตถุประสงค์ของเว็บฮุคไม่ใช่เพื่ออัปเดตเรกคอร์ดที่มีอยู่ เช่น เพื่อสร้างเรกคอร์ดใหม่ ต้องเลือกการดำเนินการ:guilabel:รันโค้ด

ทดสอบเว็บฮุค¶

การทดสอบเว็บฮุคต้องใช้เพย์โหลดทดสอบและเครื่องมือหรือระบบภายนอก เช่น Postman เพื่อส่งเพย์โหลดผ่านคำขอ API แบบ POST ส่วนนี้แสดงขั้นตอนการทดสอบเว็บฮุคใน Postman

Tip

ดู:ref:`ส่วนกรณีการใช้งานเว็บฮุค <studio/webhooks/webhook-examples>`สำหรับคำอธิบายทีละขั้นตอนของวิธีทดสอบเว็บฮุคโดยใช้เพย์โหลดทดสอบ
หากต้องการความช่วยเหลือเฉพาะเจาะจงในการทดสอบเว็บฮุคกับ Postman ให้ติดต่อทีมสนับสนุนของพวกเขา

ใน Postman ให้สร้างคำขอ HTTP ใหม่และตั้งค่าวิธีการเป็น:guilabel:POST
Copy the webhook's URL from your NightPOS database using the (link) icon and paste it into the URL field in Postman.
คลิกแท็บ:guilabel:เนื้อหา`และเลือก:guilabel:`ดิบ
ตั้งค่าประเภทไฟล์เป็น:guilabel:JSON จากนั้นคัดลอกโค้ดจากเพย์โหลดทดสอบและวางลงในตัวแก้ไขโค้ด
คลิก ส่ง

ในเครื่องมือดู Response ที่ด้านล่างของหน้าจอใน Postman รายละเอียดต่างๆ รวมถึงรหัสการตอบกลับ HTTP จะระบุว่าเว็บฮุคทำงานอย่างถูกต้องหรือไม่

A 200 OK or status: ok message indicates that the webhook is functioning properly on NightPOS's side. From here, implementation can begin with the other system to automatically send the API requests to the NightPOS webhook's URL.
If any other response is returned, the number associated with it helps to identify the problem. For example, a 500 Internal Server Error message means that NightPOS could not interpret the call properly. In this case, ensure the fields found in the JSON file are properly mapped in the webhook's configuration and in the system sending the test call.

Tip

Turning on call logging in the webhook's configuration in NightPOS provides error logs if the webhook is not functioning as intended.

ใช้งานเว็บฮุคในระบบภายนอก¶

When the webhook has been successfully created in NightPOS and tested, implement it in the system that sends data to the NightPOS database, making sure the POST API requests are sent to the webhook's URL.

กรณีการใช้งานเว็บฮุค¶

Below are two examples of how to use webhooks in NightPOS. A test payload is provided for each example, and can be found in the section on testing the webhook. Postman is used to send the test payload.

อัปเดตสกุลเงินของคำสั่งขาย¶

เว็บฮุคนี้อัปเดตคำสั่งขายในแอป การขาย เป็น USD เมื่อระบบภายนอกส่งคำขอ API แบบ POST ไปยัง URL ของเว็บฮุคที่มีหมายเลขคำสั่งขายนั้น (ซึ่งระบุโดยระเบียน id ของเพย์โหลด)

This could be useful for subsidiaries outside the United States with a mother company located inside the United States or during mergers when consolidating data into one NightPOS database.

สร้างเว็บฮุค¶

ในการสร้างเว็บฮุคนี้ ให้ดำเนินการดังนี้:

เปิดแอป การขาย จากนั้น เปิด Studio และคลิก Webhooks โมเดล คำสั่งขาย จะถูกเลือกตามค่าเริ่มต้น
คลิก ใหม่ ตัวกระตุ้น จะถูกตั้งค่าเป็น เมื่อมีเว็บฮุค ตามค่าเริ่มต้น
ตั้งค่า ระเบียนเป้าหมาย เป็น model.env[payload.get('_model')].browse(int(payload.get('_id'))) โดยที่:
- payload.get('_model') ดึงค่าที่เกี่ยวข้องกับคีย์ model ในเพย์โหลด เช่น sale.order ซึ่งเป็นชื่อทางเทคนิคของโมเดล คำสั่งขาย
- payload.get('_id') retrieves the value associated with the id key in the payload, i.e., the number of the target sales order in your NightPOS database with the S and leading zeros removed.
- int แปลง id ที่ดึงมาเป็นจำนวนเต็ม (คือ เลขจำนวนเต็ม) เนื่องจากเมธอด browse() สามารถใช้กับจำนวนเต็มเท่านั้น
คลิก เพิ่มการดำเนินการ
ในส่วน ประเภท คลิก อัปเดตระเบียน
ในส่วน Action details เลือก Update เลือกฟิลด์ Currency และเลือก USD
คลิก Save & Close

ทดสอบเว็บฮุค¶

หากต้องการทดสอบเว็บฮุคนี้ ให้ดำเนินการดังนี้:

เปิด Postman สร้างคำขอ HTTP ใหม่และตั้งค่าเมธอดเป็น POST
Copy the URL of the NightPOS webhook using the (link) icon and paste it into the URL field in Postman.
คลิกแท็บ:guilabel:เนื้อหา`และเลือก:guilabel:`ดิบ
ตั้งค่าประเภทไฟล์เป็น JSON จากนั้นคัดลอกโค้ดนี้ (เพย์โหลด) และวางลงในตัวแก้ไขโค้ด:
```
{
    "_model": "sale.order",
    "_id": "SALES ORDER NUMBER"
}
```
In your NightPOS database, choose a sales order to test the webhook on. In the pasted code, replace SALES ORDER NUMBER with the sales order's number without the S or any zeros before the number. For example, a sales order with the number S00007 should be entered as 7 in Postman.
คลิก ส่ง
ตรวจสอบ Response viewer ใน Postman เพื่อดูว่าเว็บฮุคทำงานอย่างถูกต้องหรือไม่ หากได้รับข้อความอื่นนอกเหนือจาก 200 OK หรือ status: ok หมายเลขที่เกี่ยวข้องกับข้อความจะช่วยระบุปัญหาได้

สร้างผู้ติดต่อใหม่¶

This webhook uses custom code to create a new contact in an NightPOS database when the external system sends a POST API request to the webhook's URL that includes the contact's information. This could be helpful for automatically creating new vendors or customers.

สร้างเว็บฮุค¶

ในการสร้างเว็บฮุคนี้ ให้ดำเนินการดังนี้:

เปิดแอป รายชื่อผู้ติดต่อ จากนั้น เปิดสตูดิโอ และคลิก Webhooks โมเดล Contact จะถูกเลือกโดยค่าเริ่มต้น
คลิก ใหม่ ตัวกระตุ้น จะถูกตั้งค่าเป็น เมื่อมีเว็บฮุค ตามค่าเริ่มต้น
ตั้งค่า Target Record เป็น model.browse([2]) นี่เป็นเพียงตัวยึดตำแหน่งเนื่องจากโค้ดในแอคชันอัตโนมัติจะบอกเว็บฮุคว่าต้องดึงข้อมูลอะไรจากเพย์โหลดและต้องสร้างเรคคอร์ดในโมเดลใด
คลิก เพิ่มการดำเนินการ
ในส่วน Type คลิก Execute Code

คัดลอกโค้ดนี้และวางลงในตัวแก้ไขโค้ดในแท็บ Code ของส่วน 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 NightPOS
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'")

คลิก Save & Close

ทดสอบเว็บฮุค¶

หากต้องการทดสอบเว็บฮุคนี้ ให้ดำเนินการดังนี้:

ใน Postman สร้างคำขอ HTTP ใหม่และตั้งค่าเมธอดเป็น POST
Copy the URL of the NightPOS webhook using the (link) icon and paste it into the URL field in Postman.
คลิกแท็บ:guilabel:เนื้อหา`และเลือก:guilabel:`ดิบ
ตั้งค่าประเภทไฟล์เป็น JSON จากนั้นคัดลอกโค้ดนี้ (เพย์โหลด) และวางลงในตัวแก้ไขโค้ด:
```
{
    "name": "CONTACT NAME",
    "email": "CONTACTEMAIL@EMAIL.COM",
    "phone": "CONTACT PHONE NUMBER"
}
```
ในโค้ดที่วาง ให้แทนที่ CONTACT NAME, CONTACTEMAIL@EMAIL.COM และ CONTACT PHONE NUMBER ด้วยข้อมูลของผู้ติดต่อใหม่
คลิก ส่ง
ตรวจสอบ Response viewer ใน Postman เพื่อดูว่าเว็บฮุคทำงานอย่างถูกต้องหรือไม่ หากได้รับข้อความอื่นนอกเหนือจาก 200 OK หรือ status: ok หมายเลขที่เกี่ยวข้องกับข้อความจะช่วยระบุปัญหาได้