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

請求格式

外層信封

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

會員資料（event）

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

欄位說明
action異動類型。"1"：新增、"2"：更新
memNum會員流水號
memName客戶姓名
memFirstName名字
memLastName姓氏
memMobile手機
memTel電話
memEmailEmail
memSex性別
memNickName暱稱
memCountry客戶國別
memBirthday生日（西元）
memCare貼心服務
memRemark備註
memEdm是否訂閱 EDM
memSms是否傳送簡訊
isBlacklist是否為黑名單
noMarketing行銷勿用
introducerName介紹人姓名
introducerMobile介紹人電話
introducerType介紹人身份
memAddress地址
memServiceUnit服務單位
thirdPartyCustomerId第三方客戶編號
referralDate介紹日期
memPhoto會員照片
memPipeline會員 pipeline
memEmailConfirmEmail 是否已確認
memEmailConfirmDateEmail 確認時間
memSmsConfirm簡訊是否已確認
memSmsConfirmDate簡訊確認時間
memAddressZip地址郵遞區號
memLineLINE
memWechat微信
memSkypeSkype
memQqQQ
memFbFacebook
memIgInstagram
memWhatsappWhatsApp
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