Webhooks
รับ event จาก Khuivo แบบ real-time ผ่าน HTTPS ตรวจลายเซ็นด้วย HMAC-SHA256 ดูประวัติการส่ง ส่งซ้ำ ส่งย้อนหลัง และออก signing secret ใหม่
ในหน้านี้
Webhook ส่ง event ไปยังระบบของคุณทันทีที่มีอะไรเกิดขึ้นใน workspace เช่น ลูกค้าส่งข้อความ หรือ ticket ถูกปิด เหมาะกับการซิงก์เข้า ERP, CRM หรือแจ้งเตือนในระบบของคุณเอง โดยไม่ต้องเรียก Open API วนถาม
เพิ่ม endpoint #
- 1
เปิด ตั้งค่า → Developer แล้วเลือกแท็บ Webhooks
- 2
กด เพิ่ม endpoint
- 3
ใส่ URL ปลายทาง (HTTPS) ต้องขึ้นต้นด้วย
https://และเปิดจากอินเทอร์เน็ตได้ - 4
ใส่คำอธิบาย (ไม่บังคับ) เช่น "ส่งเข้า ERP"
- 5
เลือก Event ที่ต้องการ อย่างน้อย 1 รายการ หรือกด เลือกทั้งหมด
- 6
บันทึก แล้วคัดลอก Signing secret ของ webhook ที่แสดงครั้งเดียว
- 7
กด ส่ง test event เพื่อทดสอบว่าระบบของคุณรับได้
แท็บ Webhooks ในหน้า Developer
URL ต้องเป็นที่อยู่สาธารณะ ใช้ที่อยู่ในเครือข่ายภายใน เช่น localhost หรือ IP ภายในองค์กรไม่ได้
Event ที่รับได้ #
| Event | เกิดเมื่อ |
|---|---|
message.received | ลูกค้าส่งข้อความ |
message.sent | ทีมหรือ AI ส่งข้อความ |
ticket.opened | เปิด ticket ใหม่ |
ticket.reopened | ticket ถูกเปิดอีกครั้ง |
ticket.closed | ปิด ticket |
ticket.assigned | มอบหมาย ticket |
ticket.unassigned | ยกเลิกการมอบหมาย |
ticket.field_updated | แก้ไขฟิลด์ ticket |
contact.created | มีลูกค้าใหม่ |
contact.field_updated | แก้ไขฟิลด์ลูกค้า |
ai.escalated | AI ส่งต่อให้คน |
conversion.logged | บันทึกการขาย |
channel.disconnected | ช่องทางหลุดการเชื่อมต่อ |
ปุ่ม ส่ง test event ส่ง event ชนิด webhook.test
Header ของแต่ละ request #
Khuivo ส่งเป็น POST พร้อม header:
| Header | ค่า |
|---|---|
Content-Type | application/json |
User-Agent | Khuivo-Webhooks/1.0 |
X-Khuivo-Event | ชนิด event เช่น ticket.closed |
X-Khuivo-Delivery | รหัสของการส่งครั้งนี้ |
X-Khuivo-Timestamp | เวลาที่ส่ง (unix seconds) |
X-Khuivo-Signature | ลายเซ็น v1=<hex> |
รูปแบบ payload #
{
"id": "EVENT_ID",
"type": "ticket.closed",
"version": 1,
"workspace_id": "WORKSPACE_ID",
"occurred_at": "2026-10-03T08:15:30Z",
"actor": { "type": "user", "id": "USER_ID" },
"subject": {
"ticket_id": "TICKET_ID",
"conversation_id": "CONVERSATION_ID",
"contact_id": "CONTACT_ID",
"channel_account_id": "CHANNEL_ACCOUNT_ID"
},
"data": {},
"trace_id": "TRACE_ID"
}actor.typeบอกว่าใครทำให้เกิด event:user,ai_agent,automation,systemหรือcustomersubjectมีรหัสที่เกี่ยวข้องเท่าที่มี เช่น ticket บทสนทนา ลูกค้าdataต่างกันตามชนิด event ดูตัวอย่างจริงได้จาก Request body ใน ประวัติการส่ง
ตรวจลายเซ็น #
ทุก request มีลายเซ็นเพื่อยืนยันว่ามาจาก Khuivo จริง:
- อ่าน
X-Khuivo-Timestampและ body แบบดิบ (raw) ก่อนแปลงเป็น JSON - ปฏิเสธถ้า timestamp ห่างจากเวลาปัจจุบันเกิน 5 นาที เพื่อกันการส่งซ้ำ (replay)
- คำนวณ HMAC-SHA256 ของ
<timestamp>.<raw body>ด้วย signing secret แล้วแปลงเป็น hex - เติม
v1=ข้างหน้า แล้วเทียบกับX-Khuivo-Signatureด้วยการเทียบแบบเวลาคงที่
import crypto from 'node:crypto'
import express from 'express'
const app = express()
const SECRET = process.env.KHUIVO_WEBHOOK_SECRET
app.post('/khuivo/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const timestamp = req.get('X-Khuivo-Timestamp') ?? ''
const signature = req.get('X-Khuivo-Signature') ?? ''
const age = Math.abs(Date.now() / 1000 - Number(timestamp))
if (!timestamp || !(age <= 300)) return res.status(400).send('stale timestamp')
const expected =
'v1=' + crypto.createHmac('sha256', SECRET).update(`${timestamp}.`).update(req.body).digest('hex')
const a = Buffer.from(signature)
const b = Buffer.from(expected)
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
return res.status(401).send('bad signature')
}
const event = JSON.parse(req.body.toString('utf8'))
// บันทึก event.id ไว้กันประมวลผลซ้ำ แล้วตอบ 2xx ให้เร็ว
res.sendStatus(200)
})
app.listen(3000)import hashlib
import hmac
import os
import time
from flask import Flask, abort, request
app = Flask(__name__)
SECRET = os.environ["KHUIVO_WEBHOOK_SECRET"].encode()
@app.post("/khuivo/webhook")
def khuivo_webhook():
timestamp = request.headers.get("X-Khuivo-Timestamp", "")
signature = request.headers.get("X-Khuivo-Signature", "")
if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
abort(400)
body = request.get_data() # raw bytes
digest = hmac.new(SECRET, timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(signature, "v1=" + digest):
abort(401)
event = request.get_json()
# บันทึก event["id"] ไว้กันประมวลผลซ้ำ แล้วตอบ 2xx ให้เร็ว
return "", 200การส่งซ้ำและการปิดอัตโนมัติ #
- รอคำตอบนานสุด 10 วินาที ตอบ HTTP 2xx ถือว่าสำเร็จ
- ถ้าไม่สำเร็จ ลองใหม่โดยรอนานขึ้นเรื่อย ๆ: 30 วินาที, 1 นาที, 2 นาที, 4 นาที … สูงสุดครั้งละ 1 ชั่วโมง ไปจนครบ 24 ชั่วโมง
- endpoint จะถูกปิดอัตโนมัติเมื่อส่งไม่สำเร็จต่อเนื่องนานกว่า 24 ชั่วโมง หรือไม่สำเร็จติดกัน 50 ครั้งหลังจากล้มเหลวมาแล้วอย่างน้อย 1 ชั่วโมง และเจ้าของกับแอดมินจะได้อีเมลแจ้ง
- แก้ระบบของคุณให้รับได้ แล้วเปิด endpoint อีกครั้งด้วยสวิตช์ เปิดใช้งาน จากนั้นใช้ ส่งย้อนหลัง เติม event ที่พลาดไป
ระบบอาจส่ง event เดิมมากกว่าหนึ่งครั้ง ใช้ id ใน payload กันประมวลผลซ้ำ
ประวัติการส่ง #
กด ประวัติการส่ง ที่ endpoint เพื่อดู ประวัติการส่ง (7 วัน) กรองตามสถานะ รอส่ง, สำเร็จ, ล้มเหลว, กำลังลองใหม่ ได้ กดรายการเพื่อดู รายละเอียดการส่ง: Request headers, Request body, Response body, จำนวนครั้งที่ส่ง, จะลองใหม่เมื่อ และ ข้อผิดพลาดล่าสุด
ส่งอีกครั้ง ทดสอบ และส่งย้อนหลัง #
- ส่งอีกครั้ง — ในรายละเอียดการส่ง ส่ง event นั้นซ้ำทันที
- ส่ง test event — ส่ง
webhook.testเพื่อเช็กว่า endpoint ตอบได้ - ส่งย้อนหลัง — ใช้เมื่อระบบของคุณล่มไปช่วงหนึ่ง
- 1
เปิด ประวัติการส่ง ของ endpoint
- 2
กด ส่งย้อนหลัง
- 3
เลือกเวลาที่ ตั้งแต่ (ย้อนได้ไม่เกิน 7 วัน)
- 4
กด ส่งย้อนหลัง ระบบจะแจ้งว่าเข้าคิวกี่ event
ออก signing secret ใหม่ #
- 1
ที่ endpoint กด ออก signing secret ใหม่
- 2
ยืนยัน แล้วคัดลอก Signing secret ใหม่ ที่แสดงครั้งเดียว
- 3
อัปเดต secret ในระบบของคุณทันที
เคล็ดลับ #
- ตอบ 2xx ให้เร็วที่สุด แล้วค่อยประมวลผลต่อในเบื้องหลัง เพื่อไม่ให้เกิน 10 วินาที
- เลือกเฉพาะ event ที่ใช้จริง จะลดภาระทั้งสองฝั่ง
- เก็บ signing secret ไว้ใน environment variable ไม่ใช่ในโค้ด
ปัญหาที่พบบ่อย #
- ใส่ URL ที่ขึ้นต้นด้วย https:// — webhook รองรับเฉพาะ HTTPS
- บันทึกไม่ได้เพราะ URL — URL ต้องเป็นที่อยู่สาธารณะที่เข้าถึงได้จากอินเทอร์เน็ต ระหว่างพัฒนาให้ใช้บริการ tunnel ที่ให้ URL แบบ https
- ลายเซ็นไม่ตรง — ต้องคำนวณจาก body แบบดิบ ไม่ใช่ JSON ที่ parse แล้วแปลงกลับ และตรวจว่าใช้ secret ล่าสุด
- endpoint ขึ้น ปิดอยู่ — ถูกปิดอัตโนมัติเพราะล้มเหลวต่อเนื่อง ดูสาเหตุใน ข้อผิดพลาดล่าสุด แก้แล้วเปิดใช้งานอีกครั้ง
- ส่ง test event ไม่สำเร็จ — เปิด ประวัติการส่ง ดู status code และ Response body ที่ระบบของคุณตอบกลับ
หน้านี้มีประโยชน์ไหม?