跳到主要內容
客脈 Kemai文件中心
文件選單 開發者 API

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 相同。

事件類型

typedata
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,以小寫十六進位表示。

接收端請:

  1. 用原始的請求內容(收到的位元組,不要先解析成 JSON 再轉回字串)計算簽章,用固定時間的比較方式和 v1 比對。
  2. 拒絕 t 和現在差超過 5 分鐘的請求,避免舊的請求被重放。
  3. 驗證通過才處理內容。

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。

相關文件