Skip to main content

會員資料異動 Webhook 說明

會員資料異動 Webhook 說明（member_info）

當貴公司的會員資料新增或更新時，iftek 平台會主動以 HTTP POST 把事件推送到貴公司設定的 webhookUrl。 本文件說明請求格式，供貴公司實作「接收端點」。

目錄

總覽

項目 內容
觸發時機 貴公司會員資料新增或更新時
方向 iftek 平台 → 貴公司（由 iftek 主動呼叫）
方法 POST
端點 貴公司於 iftek 後台設定的 webhookUrl（由貴公司自行實作部署）
內容格式 application/json;charset=UTF-8
事件類型 member_info

運作流程

會員資料新增/更新
        │
        ▼
iftek 平台組裝 member_info 事件
        │
        ▼
POST → 貴公司 webhookUrl（帶 X-Iftek-Signature）
        │
        ▼
貴公司驗證簽章 → 處理資料 → 回應 HTTP 200

推送與重送機制

  • 平台僅在貴公司已啟用 webhook（isEnabled = Y）時才會推送。
  • 貴公司端必須回應 HTTP 200 代表接收成功；回任何非 200（或連線失敗）都會被視為失敗。
  • 失敗後平台會排程延遲約 30 分鐘重送一次；重送仍失敗則不再重送。
  • 每次推送都有唯一的 uuid，貴公司可用它做冪等（去重）處理，避免重送造成重複處理。

簽章驗證（X-Iftek-Signature）

每個請求都會帶 header X-Iftek-Signature，用於確認來源與內容未被竄改。

簽章計算方式：

X-Iftek-Signature = HmacSHA256(原始 request body 字串, 公司專屬 secret)
                    → 輸出為小寫 hex 字串

驗證步驟：

  1. 取得收到的「原始 request body 字串」（請勿先反序列化再重組，務必用原始字串）。
  2. 以貴公司專屬的 secret 對該字串做 HmacSHA256，輸出小寫 hex。
  3. 將計算結果與 header X-Iftek-Signature 比對，一致才接受。

🔐 secret 由 iftek 提供，請妥善保管。

請求 Headers：

Header 必填 說明
X-Iftek-Signature ✅ HmacSHA256(requestBody, secret) 的小寫 hex 字串
Content-Type ✅ application/json;charset=UTF-8

請求格式

外層信封

欄位 型別 說明
timestamp string 推送當下的 epoch 毫秒時間戳（字串），例："1748505600000"
uuid string (uuid) 此次推送的唯一識別碼，可用於冪等去重
eventType string 事件類型，會員資料異動固定為 member_info
event object 會員資料異動內容，見下表

會員資料（event）

action 一定有值；其餘欄位是否有值，取決於貴公司「會員設定頁」是否啟用該欄位。未啟用 / 被隱藏的欄位其值為 null（欄位仍會存在於 JSON 中）。

欄位 說明
action 異動類型。"1"：新增、"2"：更新
memNum 會員流水號
memName 客戶姓名
memFirstName 名字
memLastName 姓氏
memMobile 手機
memTel 電話
memEmail Email
memSex 性別
memNickName 暱稱
memCountry 客戶國別
memBirthday 生日（西元）
memCare 貼心服務
memRemark 備註
memEdm 是否訂閱 EDM
memSms 是否傳送簡訊
isBlacklist 是否為黑名單
noMarketing 行銷勿用
introducerName 介紹人姓名
introducerMobile 介紹人電話
introducerType 介紹人身份
memAddress 地址
memServiceUnit 服務單位
thirdPartyCustomerId 第三方客戶編號
referralDate 介紹日期
memPhoto 會員照片
memPipeline 會員 pipeline
memEmailConfirm Email 是否已確認
memEmailConfirmDate Email 確認時間
memSmsConfirm 簡訊是否已確認
memSmsConfirmDate 簡訊確認時間
memAddressZip 地址郵遞區號
memLine LINE
memWechat 微信
memSkype Skype
memQq QQ
memFb Facebook
memIg Instagram
memWhatsapp WhatsApp
createUser 建立人員
createDate 建立時間
updateUser 更新人員
updateDate 更新時間
createMem 建立會員流水號
updateMem 更新會員流水號
memPoint 會員積點
memRoadNum 道路流水號
memCityNum 城市流水號
memZipNum 郵遞區號流水號
introducerMemNum 介紹會員流水號
customFields 客戶自訂欄位（物件），見下節

自訂欄位（customFields）

貴公司在系統「會員設定頁」自訂的欄位放在這裡：

  • key：該欄位的 apiCode（由貴公司在系統設定）。
  • value：該欄位的內容，格式依欄位類型（mscType）而定。
mscType 類型 value 內容 範例
1 日期(西元) 西元日期字串 "2024-03-15"
2 日期(農曆) 組合字串 {干支}年{閏?}{月}月{日}日 "甲子年閏4月15日"
3 文字框 文字 "自由輸入內容"
4 文字區域 多行文字 "第一行\n第二行"
5 城市 城市名稱（由 cityNum 轉名稱） "臺北市"
6 區域 區域名稱（由郵遞區號 pk 轉名稱） "中正區"
7 道路 道路名稱（由 roadNum 轉名稱） "忠孝東路"
8 地址 地址字串 "忠孝東路一段1號"
9 郵遞區號 郵遞區號字串 "100"
10 特殊標籤 標籤名稱（已去除單引號） "VIP"

備註：

  • mscType 0（系統預設欄位）與 11（數字，客製元件無法使用）不會出現在 customFields。
  • 日期(農曆)、城市、區域、道路、郵遞區號、特殊標籤這幾類，當該欄位無值時，其 key 不會出現在 customFields 中。

回應要求

貴公司回應 平台判定
HTTP 200 ✅ 接收成功
非 200 或連線失敗 ❌ 失敗，約 30 分鐘後重送一次

⚠️ 請務必在處理成功後回 200，否則平台會判定失敗並重送。

完整範例

Headers

POST /your-webhook-url HTTP/1.1
Content-Type: application/json;charset=UTF-8
X-Iftek-Signature: 3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b

Body

{
  "timestamp": "1748505600000",
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "eventType": "member_info",
  "event": {
    "action": "2",
    "memNum": 100123,
    "memName": "王小明",
    "memMobile": "0912345678",
    "memEmail": "[email protected]",
    "memSex": "1",
    "memBirthday": "1990-01-01",
    "memRemark": null,
    "customFields": {
      "custom_birthday_lunar": "甲子年閏4月15日",
      "custom_city": "臺北市",
      "custom_zone": "中正區",
      "custom_remark_area": "第一行\n第二行",
      "custom_vip_tag": "VIP"
    }
  }
}

注意事項

  • 簽章務必以「原始 request body 字串」計算，不要先解析再重組字串，否則簽章會對不上。
  • 請以 uuid 做冪等處理，避免重送導致重複新增 / 更新。
  • 會員本體欄位即使「未啟用」也會存在於 JSON 中，其值為 null，請容許 null。
  • ⚠️ outbound webhook（本文件）輸出的城市 / 區域 / 道路是「名稱」字串；而匯入 API（新增/更新會員）需要的是「pk 數字」，兩者格式不同，串接回拋時請勿直接沿用。
Back to top