Khuivo
นักพัฒนา

Webhooks

รับ event จาก Khuivo แบบ real-time ผ่าน HTTPS ตรวจลายเซ็นด้วย HMAC-SHA256 ดูประวัติการส่ง ส่งซ้ำ ส่งย้อนหลัง และออก signing secret ใหม่

ในหน้านี้

Webhook ส่ง event ไปยังระบบของคุณทันทีที่มีอะไรเกิดขึ้นใน workspace เช่น ลูกค้าส่งข้อความ หรือ ticket ถูกปิด เหมาะกับการซิงก์เข้า ERP, CRM หรือแจ้งเตือนในระบบของคุณเอง โดยไม่ต้องเรียก Open API วนถาม

เพิ่ม endpoint #

  1. 1

    เปิด ตั้งค่า → Developer แล้วเลือกแท็บ Webhooks

  2. 2

    กด เพิ่ม endpoint

  3. 3

    ใส่ URL ปลายทาง (HTTPS) ต้องขึ้นต้นด้วย https:// และเปิดจากอินเทอร์เน็ตได้

  4. 4

    ใส่คำอธิบาย (ไม่บังคับ) เช่น "ส่งเข้า ERP"

  5. 5

    เลือก Event ที่ต้องการ อย่างน้อย 1 รายการ หรือกด เลือกทั้งหมด

  6. 6

    บันทึก แล้วคัดลอก Signing secret ของ webhook ที่แสดงครั้งเดียว

  7. 7

    กด ส่ง test event เพื่อทดสอบว่าระบบของคุณรับได้

    แท็บ Webhooks ในหน้า Developer

URL ต้องเป็นที่อยู่สาธารณะ ใช้ที่อยู่ในเครือข่ายภายใน เช่น localhost หรือ IP ภายในองค์กรไม่ได้

Event ที่รับได้ #

Eventเกิดเมื่อ
message.receivedลูกค้าส่งข้อความ
message.sentทีมหรือ AI ส่งข้อความ
ticket.openedเปิด ticket ใหม่
ticket.reopenedticket ถูกเปิดอีกครั้ง
ticket.closedปิด ticket
ticket.assignedมอบหมาย ticket
ticket.unassignedยกเลิกการมอบหมาย
ticket.field_updatedแก้ไขฟิลด์ ticket
contact.createdมีลูกค้าใหม่
contact.field_updatedแก้ไขฟิลด์ลูกค้า
ai.escalatedAI ส่งต่อให้คน
conversion.loggedบันทึกการขาย
channel.disconnectedช่องทางหลุดการเชื่อมต่อ

ปุ่ม ส่ง test event ส่ง event ชนิด webhook.test

Header ของแต่ละ request #

Khuivo ส่งเป็น POST พร้อม header:

Headerค่า
Content-Typeapplication/json
User-AgentKhuivo-Webhooks/1.0
X-Khuivo-Eventชนิด event เช่น ticket.closed
X-Khuivo-Deliveryรหัสของการส่งครั้งนี้
X-Khuivo-Timestampเวลาที่ส่ง (unix seconds)
X-Khuivo-Signatureลายเซ็น v1=<hex>

รูปแบบ payload #

ตัวอย่าง ticket.closed
{
  "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 หรือ customer
  • subject มีรหัสที่เกี่ยวข้องเท่าที่มี เช่น ticket บทสนทนา ลูกค้า
  • data ต่างกันตามชนิด event ดูตัวอย่างจริงได้จาก Request body ใน ประวัติการส่ง

ตรวจลายเซ็น #

ทุก request มีลายเซ็นเพื่อยืนยันว่ามาจาก Khuivo จริง:

  1. อ่าน X-Khuivo-Timestamp และ body แบบดิบ (raw) ก่อนแปลงเป็น JSON
  2. ปฏิเสธถ้า timestamp ห่างจากเวลาปัจจุบันเกิน 5 นาที เพื่อกันการส่งซ้ำ (replay)
  3. คำนวณ HMAC-SHA256 ของ <timestamp>.<raw body> ด้วย signing secret แล้วแปลงเป็น hex
  4. เติม v1= ข้างหน้า แล้วเทียบกับ X-Khuivo-Signature ด้วยการเทียบแบบเวลาคงที่
Node.js (Express)
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)
Python (Flask)
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. 1

    เปิด ประวัติการส่ง ของ endpoint

  2. 2

    กด ส่งย้อนหลัง

  3. 3

    เลือกเวลาที่ ตั้งแต่ (ย้อนได้ไม่เกิน 7 วัน)

  4. 4

    กด ส่งย้อนหลัง ระบบจะแจ้งว่าเข้าคิวกี่ event

ออก signing secret ใหม่ #

  1. 1

    ที่ endpoint กด ออก signing secret ใหม่

  2. 2

    ยืนยัน แล้วคัดลอก Signing secret ใหม่ ที่แสดงครั้งเดียว

  3. 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 ที่ระบบของคุณตอบกลับ

หน้านี้มีประโยชน์ไหม?