#การผสานรวม Webhook ของเวิร์กโฟลว์

ด้วย Webhook trigger, NocoBase สามารถรับการเรียกใช้ HTTP จากระบบภายนอก และเรียกใช้เวิร์กโฟลว์ได้โดยอัตโนมัติ ทำให้การผสานรวมกับระบบภายนอกเป็นไปอย่างราบรื่นครับ/ค่ะ

#ภาพรวม

Webhook คือกลไก "Reverse API" ที่ช่วยให้ระบบภายนอกสามารถส่งข้อมูลมายัง NocoBase ได้เองเมื่อเกิดเหตุการณ์บางอย่างขึ้นครับ/ค่ะ ซึ่งแตกต่างจากการตรวจสอบข้อมูล (polling) แบบปกติ Webhook จะช่วยให้การผสานรวมข้อมูลเป็นไปอย่างรวดเร็วและมีประสิทธิภาพมากยิ่งขึ้น

#กรณีการใช้งานทั่วไป

#การส่งข้อมูลจากแบบฟอร์ม

ระบบแบบสำรวจภายนอก, แบบฟอร์มลงทะเบียน, หรือแบบฟอร์มข้อเสนอแนะจากลูกค้า สามารถส่งข้อมูลมายัง NocoBase ผ่าน Webhook ได้ทันทีหลังจากผู้ใช้ส่งข้อมูล ซึ่งจะช่วยสร้างบันทึกข้อมูลโดยอัตโนมัติ และเรียกใช้กระบวนการทำงานต่อเนื่องได้ทันที (เช่น การส่งอีเมลยืนยัน, การมอบหมายงาน เป็นต้น)

#การแจ้งเตือนข้อความ

เหตุการณ์จากแพลตฟอร์มข้อความภายนอก (เช่น WeCom, DingTalk, Slack) อย่างข้อความใหม่, การกล่าวถึง (@), หรือการอนุมัติที่เสร็จสมบูรณ์ สามารถเรียกใช้กระบวนการอัตโนมัติใน NocoBase ผ่าน Webhook ได้ครับ/ค่ะ

#การซิงค์ข้อมูล

เมื่อข้อมูลในระบบภายนอก (เช่น CRM, ERP) มีการเปลี่ยนแปลง Webhook จะส่งข้อมูลอัปเดตมายัง NocoBase แบบเรียลไทม์ เพื่อให้ข้อมูลเป็นปัจจุบันอยู่เสมอครับ/ค่ะ

#การผสานรวมกับบริการภายนอก

• GitHub: เหตุการณ์การ push โค้ด, การสร้าง PR (Pull Request) จะเรียกใช้เวิร์กโฟลว์อัตโนมัติ
• GitLab: การแจ้งเตือนสถานะของ CI/CD pipeline
• การส่งแบบฟอร์ม: ระบบแบบฟอร์มภายนอกส่งข้อมูลมายัง NocoBase
• อุปกรณ์ IoT: การเปลี่ยนแปลงสถานะอุปกรณ์, การรายงานข้อมูลจากเซ็นเซอร์

#คุณสมบัติเด่น

#กลไกการเรียกใช้ที่ยืดหยุ่น

• รองรับ HTTP method ต่างๆ เช่น GET, POST, PUT, DELETE
• สามารถแยกวิเคราะห์ (parse) ข้อมูลในรูปแบบ JSON, form data และรูปแบบอื่นๆ ที่ใช้กันทั่วไปได้โดยอัตโนมัติ
• กำหนดค่าการตรวจสอบคำขอ (request validation) เพื่อให้แน่ใจว่าข้อมูลมาจากแหล่งที่เชื่อถือได้

#ความสามารถในการประมวลผลข้อมูล

• ข้อมูลที่ได้รับสามารถนำไปใช้เป็นตัวแปรในเวิร์กโฟลว์ได้
• รองรับการแปลงและประมวลผลข้อมูลที่ซับซ้อน
• สามารถทำงานร่วมกับโหนดเวิร์กโฟลว์อื่นๆ เพื่อสร้างตรรกะทางธุรกิจที่ซับซ้อนได้

#การรับรองความปลอดภัย

• รองรับการตรวจสอบลายเซ็น (signature verification) เพื่อป้องกันการปลอมแปลงคำขอ
• กำหนดค่า IP whitelist ได้
• การส่งข้อมูลแบบเข้ารหัสด้วย HTTPS

#ขั้นตอนการใช้งาน

#1. ติดตั้งปลั๊กอิน

ค้นหาและติดตั้งปลั๊กอิน เวิร์กโฟลว์: Webhook trigger ในตัวจัดการปลั๊กอินครับ/ค่ะ

หมายเหตุ: ปลั๊กอินนี้เป็นปลั๊กอินเชิงพาณิชย์ ซึ่งต้องซื้อหรือสมัครสมาชิกแยกต่างหากครับ/ค่ะ

#2. สร้างเวิร์กโฟลว์ Webhook

1. ไปที่หน้า การจัดการเวิร์กโฟลว์
2. คลิก สร้างเวิร์กโฟลว์
3. เลือก Webhook trigger เป็นประเภทการเรียกใช้

4. กำหนดค่าพารามิเตอร์ Webhook

• Request Path (เส้นทางคำขอ): กำหนดเส้นทาง URL ของ Webhook เอง
• Request Method (เมธอดคำขอ): เลือก HTTP method ที่อนุญาต (GET/POST/PUT/DELETE)
• Sync/Async (ซิงค์/อะซิงค์): เลือกว่าจะรอให้เวิร์กโฟลว์ทำงานเสร็จสิ้นก่อนส่งผลลัพธ์กลับไปหรือไม่
• Validation (การตรวจสอบ): กำหนดค่าการตรวจสอบลายเซ็นหรือกลไกความปลอดภัยอื่นๆ

#3. กำหนดค่าโหนดเวิร์กโฟลว์

เพิ่มโหนดเวิร์กโฟลว์ตามความต้องการทางธุรกิจของคุณ เช่น:

• Collection Operations (การดำเนินการกับคอลเลกชัน): สร้าง, อัปเดต, ลบข้อมูล
• Conditional Logic (ตรรกะเงื่อนไข): แยกเส้นทางการทำงานตามข้อมูลที่ได้รับ
• HTTP Request (คำขอ HTTP): เรียกใช้ API อื่นๆ
• Notifications (การแจ้งเตือน): ส่งอีเมล, SMS เป็นต้น
• Custom Code (โค้ดที่กำหนดเอง): รันโค้ด JavaScript

#4. รับ Webhook URL

หลังจากสร้างเวิร์กโฟลว์แล้ว ระบบจะสร้าง Webhook URL ที่ไม่ซ้ำกัน โดยปกติจะมีรูปแบบดังนี้:

https://your-nocobase-domain.com/api/webhooks/your-workflow-key

#5. กำหนดค่าในระบบภายนอก

กำหนดค่า Webhook URL ที่สร้างขึ้นในระบบภายนอก:

• กำหนดที่อยู่ callback สำหรับการส่งข้อมูลในระบบแบบฟอร์ม
• กำหนดค่า Webhook ใน GitHub/GitLab
• กำหนดที่อยู่สำหรับ push เหตุการณ์ใน WeCom/DingTalk

#6. ทดสอบ Webhook

ใช้เครื่องมือ (เช่น Postman, cURL) เพื่อทดสอบ Webhook:

curl -X POST https://your-nocobase-domain.com/api/webhooks/your-workflow-key \
  -H "Content-Type: application/json" \
  -d '{"event":"test","data":{"message":"Hello NocoBase"}}'

#การเข้าถึงข้อมูลคำขอ

ในเวิร์กโฟลว์ คุณสามารถเข้าถึงข้อมูลที่ Webhook ได้รับผ่านตัวแปรต่างๆ ดังนี้:

• {{$context.data}}: ข้อมูลในส่วนเนื้อหา (request body) ของคำขอ
• {{$context.headers}}: ข้อมูลส่วนหัว (headers) ของคำขอ
• {{$context.query}}: พารามิเตอร์ query ใน URL
• {{$context.params}}: พารามิเตอร์ในเส้นทาง (path parameters)

#การกำหนดค่าการตอบกลับ

#โหมดซิงโครนัส (Synchronous Mode)

จะส่งผลลัพธ์กลับไปหลังจากเวิร์กโฟลว์ทำงานเสร็จสิ้น โดยสามารถกำหนดค่าได้ดังนี้:

• Response Status Code (รหัสสถานะการตอบกลับ): เช่น 200, 201 เป็นต้น
• Response Data (ข้อมูลการตอบกลับ): กำหนดข้อมูล JSON ที่จะส่งกลับไปเอง
• Response Headers (ส่วนหัวการตอบกลับ): กำหนด HTTP header เอง

#โหมดอะซิงโครนัส (Asynchronous Mode)

จะส่งการยืนยันกลับไปทันที และเวิร์กโฟลว์จะทำงานอยู่เบื้องหลัง เหมาะสำหรับ:

• เวิร์กโฟลว์ที่ใช้เวลานานในการทำงาน
• กรณีที่ไม่ต้องการผลลัพธ์การทำงานกลับไป
• กรณีที่มีการเรียกใช้พร้อมกันจำนวนมาก (high-concurrency)

#แนวทางปฏิบัติที่ดีที่สุดด้านความปลอดภัย

#1. เปิดใช้งานการตรวจสอบลายเซ็น

บริการภายนอกส่วนใหญ่รองรับกลไกการตรวจสอบลายเซ็น:

// ตัวอย่าง: ตรวจสอบลายเซ็น GitHub Webhook
const crypto = require('crypto');
const signature = context.headers['x-hub-signature-256'];
const payload = JSON.stringify(context.data);
const secret = 'your-webhook-secret';
const expectedSignature = 'sha256=' + crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');

if (signature !== expectedSignature) {
  throw new Error('Invalid signature');
}

#2. ใช้ HTTPS

ตรวจสอบให้แน่ใจว่า NocoBase ถูกติดตั้งในสภาพแวดล้อม HTTPS เพื่อปกป้องความปลอดภัยในการส่งข้อมูลครับ/ค่ะ

#3. จำกัดแหล่งที่มาของคำขอ

กำหนดค่า IP whitelist เพื่ออนุญาตเฉพาะคำขอจากแหล่งที่เชื่อถือได้เท่านั้น

#4. การตรวจสอบความถูกต้องของข้อมูล

เพิ่มตรรกะการตรวจสอบความถูกต้องของข้อมูลในเวิร์กโฟลว์ เพื่อให้แน่ใจว่าข้อมูลที่ได้รับมีรูปแบบที่ถูกต้องและเนื้อหาที่ถูกต้องตามกฎหมาย

#5. การตรวจสอบบันทึก (Log Audit)

บันทึกคำขอ Webhook ทั้งหมด เพื่อให้ง่ายต่อการติดตามและแก้ไขปัญหา

#การแก้ไขปัญหาทั่วไป

#Webhook ไม่ทำงานใช่ไหม?

1. ตรวจสอบว่า Webhook URL ถูกต้องหรือไม่
2. ตรวจสอบว่าสถานะของเวิร์กโฟลว์เป็น "เปิดใช้งาน" (Enabled)
3. ตรวจสอบบันทึกการส่งของระบบภายนอก
4. ตรวจสอบการตั้งค่าไฟร์วอลล์และเครือข่าย

#จะดีบัก Webhook ได้อย่างไร?

1. ตรวจสอบบันทึกการทำงานของเวิร์กโฟลว์ เพื่อดูรายละเอียดของคำขอและผลลัพธ์การเรียกใช้
2. ใช้เครื่องมือทดสอบ Webhook (เช่น Webhook.site) เพื่อตรวจสอบคำขอ
3. ตรวจสอบข้อมูลสำคัญและข้อความแสดงข้อผิดพลาดในบันทึกการทำงาน

#จะจัดการกับการลองใหม่ (Retries) ได้อย่างไร?

บริการภายนอกบางอย่างจะลองส่งข้อมูลอีกครั้ง หากไม่ได้รับการตอบกลับที่สำเร็จ:

• ตรวจสอบให้แน่ใจว่าเวิร์กโฟลว์มีความสามารถในการทำงานซ้ำได้ (idempotent)
• ใช้ตัวระบุที่ไม่ซ้ำกันเพื่อขจัดข้อมูลซ้ำซ้อน
• บันทึก ID คำขอที่ได้รับการประมวลผลแล้ว

#คำแนะนำในการเพิ่มประสิทธิภาพ

• ใช้โหมดอะซิงโครนัสสำหรับการดำเนินการที่ใช้เวลานาน
• เพิ่มตรรกะเงื่อนไขเพื่อกรองคำขอที่ไม่จำเป็นต้องประมวลผล
• พิจารณาใช้ Message Queue เพื่อจัดการกับสถานการณ์ที่มีการเรียกใช้พร้อมกันจำนวนมาก

#ตัวอย่างสถานการณ์

#การประมวลผลการส่งแบบฟอร์มภายนอก

// 1. ตรวจสอบแหล่งที่มาของข้อมูล
// 2. แยกวิเคราะห์ข้อมูลแบบฟอร์ม
const formData = context.data;

// 3. สร้างบันทึกลูกค้า
// 4. มอบหมายให้ผู้รับผิดชอบที่เกี่ยวข้อง
// 5. ส่งอีเมลยืนยันไปยังผู้ส่ง
if (formData.email) {
  // ส่งอีเมลแจ้งเตือน
}

#การแจ้งเตือนการ push โค้ด GitHub

// 1. แยกวิเคราะห์ข้อมูลการ push
const commits = context.data.commits;
const branch = context.data.ref.replace('refs/heads/', '');

// 2. ถ้าเป็น main branch
if (branch === 'main') {
  // 3. เรียกใช้กระบวนการ deploy
  // 4. แจ้งเตือนสมาชิกในทีม
}

#แหล่งข้อมูลที่เกี่ยวข้อง

• เอกสารปลั๊กอินเวิร์กโฟลว์
• เวิร์กโฟลว์: Webhook trigger
• เวิร์กโฟลว์: โหนดคำขอ HTTP
• การยืนยันตัวตนด้วย API Key