Webhook
客脈送出的 webhook 事件格式、標頭、每種事件的內容、簽章驗證範例,以及重試、重複與順序的處理方式。
工作區在「API 與 Webhook」設定 Webhook 後,資料有異動時客脈會對你的網址送出 POST 請求。設定方式見Webhook。
請求格式
POST /你的路徑 HTTP/1.1
Content-Type: application/json
User-Agent: Kemai-Webhook/1.0
X-Kemai-Event: contact.created
X-Kemai-Delivery: 0b5c6f0e-8d2a-4a3e-9a51-3c1f2e7d9b40
X-Kemai-Signature: t=1793845800,v1=5f2b9c…{
"id": "6a1d2f9e-3b7c-4e8a-9f20-1c5d7e9a0b34",
"type": "contact.created",
"occurred_at": "2026-11-04T02:30:00.000Z",
"workspace": "acme",
"origin": null,
"data": { "id": "c2f6e1a8-5d3b-4f7e-8a91-2b4c6d8e0f13" }
}| 欄位 | 說明 |
|---|---|
id | 事件的 id。重試與手動重送都是同一個 id,用來判斷是否已經處理過 |
type | 事件類型,見下表 |
occurred_at | 事件發生的時間(UTC) |
workspace | 工作區的子網域名稱 |
origin | 變更的來源:null 是一般操作(畫面、匯入),api 是經由 API Key,automation 是自動化流程 |
data | 事件內容,只有 id;需要完整資料時用 API Key 讀取 |
標頭的 X-Kemai-Delivery 是這次傳送的 id,每次重送都不同;X-Kemai-Event 和內容的 type 相同。
事件類型
type | data |
|---|---|
company.created | { "id" } |
company.updated | { "id", "fields" }:改了哪些欄位,例如 ["phone", "custom.source"] |
company.deleted | { "id" } |
contact.created | { "id" } |
contact.updated | { "id", "fields" } |
contact.deleted | { "id" } |
deal.created | { "id" } |
deal.updated | { "id", "fields" } |
deal.deleted | { "id" } |
deal.stage_changed | { "id", "pipelineId", "fromStageId", "toStageId" } |
activity.created | { "id", "subjectType", "subjectId" } |
task.created | { "id" } |
task.completed | { "id" } |
ping | {}:按「傳送測試事件」時送出 |
- 商機換階段一定會送出
deal.stage_changed。用PATCH改stageId時另外會送出deal.updated(fields含stageId);在看板拖拉或用move移動則只送deal.stage_changed。只關心換階段的話,訂閱deal.stage_changed就好。 - 只改標籤不會送出
updated事件。 - 之後可能新增事件類型或
data的欄位,請忽略不認得的部分。
驗證簽章
X-Kemai-Signature 的格式是 t=<時間戳>,v1=<簽章>:
t是送出時的 Unix 秒數。v1是用簽章密鑰(whsec_開頭的整串文字)對「t+.+ 原始的請求內容」計算的 HMAC-SHA256,以小寫十六進位表示。
接收端請:
- 用原始的請求內容(收到的位元組,不要先解析成 JSON 再轉回字串)計算簽章,用固定時間的比較方式和
v1比對。 - 拒絕
t和現在差超過 5 分鐘的請求,避免舊的請求被重放。 - 驗證通過才處理內容。
Node.js 範例:
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyKemaiSignature(secret, rawBody, header, toleranceSeconds = 300) {
const parts = Object.fromEntries(header.split(",").map((part) => part.split("=", 2)));
const timestamp = Number(parts.t);
if (!Number.isInteger(timestamp) || !parts.v1) return false;
if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;
const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(parts.v1);
return a.length === b.length && timingSafeEqual(a, b);
}Python 範例:
import hashlib
import hmac
import time
def verify_kemai_signature(secret: str, raw_body: bytes, header: str, tolerance: int = 300) -> bool:
parts = dict(part.split("=", 1) for part in header.split(","))
try:
timestamp = int(parts["t"])
except (KeyError, ValueError):
return False
if abs(time.time() - timestamp) > tolerance:
return False
message = f"{timestamp}.".encode() + raw_body
expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))回應
- 在 10 秒內回應
2xx就算成功;回應的內容會被忽略。 - 其他狀態碼、逾時、連線失敗都算失敗。客脈不跟隨轉址,回應
301、302也算失敗,請填最終的網址。 - 處理比較久的工作請先回
200,再在背景處理。
重試與重複
- 失敗時自動重試,間隔大約 30 秒、1 分鐘、2 分鐘、4 分鐘,總共最多 5 次。
- 都失敗時這次傳送記為「失敗」,可以在傳送紀錄按「重送」。
- 連續 20 次傳送失敗,Webhook 會自動停用,並通知擁有者與管理員。
- 同一個事件可能送達不只一次(例如你已處理但回應太慢)。請記下處理過的事件
id,重複的直接回200。 - 事件不保證依發生順序送達。需要最新狀態時,用 API Key 讀取那筆資料,或比較
occurred_at。