Logo Site EngageLab Mark Colored Transparent文件
OTP
文檔首頁
文件API 參考
搜尋
登錄
API 參考/回調配置
API 參考回調配置...

回調配置說明

最新更新：7 天前

本節介紹如何配置 EngageLab OTP 的回調地址，以及相關的安全校驗機制，確保回調資料的可靠性與安全性。

回調地址配置與校驗

配置回調地址後，EngageLab OTP 會自動向該地址發送一次 HTTP POST 請求，用於校驗介面的可用性。您的服務需在 3 秒內返回 HTTP 200 狀態碼，否則系統會認為該地址不可用。

注意：
為確保能夠正常接收回調資料，請將 119.8.170.74 和 114.119.180.30 加入您的伺服器防火牆白名單。

請求範例

假設您的回調地址為 https://example.engagelabotp.callback.com，系統會發送如下請求：

curl -X POST https://example.engagelabotp.callback.com -d '{}'
              
              curl -X POST https://example.engagelabotp.callback.com -d '{}'
此代碼塊在浮窗中顯示

回應要求

您的服務只需返回 HTTP 200 狀態碼，無需返回任何內容。例如：

HTTP/1.1 200 OK Content-Length: 0
              
              HTTP/1.1 200 OK
Content-Length: 0
此代碼塊在浮窗中顯示

注意：
回調地址校驗僅判斷 HTTP 狀態碼，不要求返回具體報文內容。請確保您的服務介面能在 3 秒內正確回應 200。

回調安全機制

為保障回調資料的安全性和來源可信，EngageLab OTP 支援多種安全校驗方式。

使用者名稱與金鑰校驗（可選）

  • 可選配置。如果設置了使用者名稱，必須同時設置金鑰。
  • 配置後，EngageLab 在每次回調請求的 HTTP Header 中添加 X-CALLBACK-ID 欄位，格式如下：
X-CALLBACK-ID: timestamp={timestamp};nonce={nonce};username={username};signature={signature}
              
              X-CALLBACK-ID: timestamp={timestamp};nonce={nonce};username={username};signature={signature}
此代碼塊在浮窗中顯示
  • 其中：
    • timestamp：回調發送的時間戳
    • nonce：隨機數
    • username：您配置的使用者名稱
    • signature：簽名資訊，計算方法如下

簽名計算方式（Python 範例）

import hashlib, hmac def verify(username, secret, timestamp, nonce, signature): return signature == hmac.new( key=secret.encode(), msg=f'{timestamp}{nonce}{username}'.encode(), digestmod=hashlib.sha256 ).hexdigest()
              
              import hashlib, hmac
def verify(username, secret, timestamp, nonce, signature):
    return signature == hmac.new(
        key=secret.encode(),
        msg=f'{timestamp}{nonce}{username}'.encode(),
        digestmod=hashlib.sha256
    ).hexdigest()
此代碼塊在浮窗中顯示
  • 伺服器端可用上述方式校驗回調請求的合法性。

Authorization 鑑權（可選）

  • 如果您的回調介面需要鑑權（如 Basic Auth、Bearer Token 等），可在配置時填寫 Authorization 資訊。
  • EngageLab 在請求時會自動攜帶該 Authorization 欄位，便於您的服務校驗請求身份。

回調事件說明

訊息狀態

訊息狀態用於追蹤每一條訊息在生命週期中的狀態變化。用於即時了解訊息的發送、送達、驗證等各個環節的進展，便於統計分析、異常處理和使用者體驗最佳化。

事件標識 說明
plan 訊息計畫發送，進入待發送佇列
target_valid 目標號碼有效
target_invalid 目標號碼無效
sent 訊息成功發送
sent_failed 訊息發送失敗
delivered 訊息送達用戶設備
delivered_failed 訊息已發送，但未能送達用戶設備
verified 用戶已成功完成 OTP 驗證
verified_failed 用戶驗證失敗
verified_timeout 用戶未在規定時間內完成驗證，已超時

回調資料結構

外層結構

{ "total": 1, "rows": [ { // ReportLifecycle 物件 } ] }
              
              {
  "total": 1,
  "rows": [
    {
      // ReportLifecycle 物件
    }
  ]
}
此代碼塊在浮窗中顯示
欄位名 類型 說明
total int 本次回調包含的資料筆數
rows array 生命週期狀態資料陣列

ReportLifecycle 物件

欄位名 類型 說明
message_id string 訊息唯一 ID
to string 接收方號碼
server string 服務類型（如 otp）
channel string 管道類型
itime int64 回調時間戳（秒）
custom_args object 自訂參數（如有傳入則回傳）
status object 狀態詳情物件

status 物件

欄位名 類型 說明
message_status string 訊息當前狀態（見下表）
status_data object 狀態資料物件
billing object 計費資訊物件（有計費時返回）
error_code int 錯誤碼，0 表示無錯誤
error_detail object 錯誤詳情（發生錯誤時返回）

status_data 物件

欄位名 類型 說明
msg_time int64 訊息建立時間戳（秒）
message_id string 訊息 ID
current_send_channel string 當前發送管道名稱
template_key string 範本配置 Key
business_id string 業務 ID

billing 物件（有計費時返回）

欄位名 類型 說明
cost float64 費用金額
currency string 幣種，固定為 "USD"

一般僅 sent 階段的訊息包含計費資訊。

error_detail 物件（發生錯誤時返回）

欄位名 類型 說明
message string 錯誤訊息描述

範例：訊息發送成功

{ "total": 1, "rows": [ { "message_id": "123456789", "to": "+6598765432", "server": "sms", "channel": "sms", "itime": 1701234567, "custom_args": { "order_id": "ORDER123", "user_id": "USER456" }, "status": { "message_status": "sent", "status_data": { "msg_time": 1701234560, "message_id": "123456789", "current_send_channel": "CHANNEL_A", "template_key": "verify_code", "business_id": "1001" }, "billing": { "cost": 0.005, "currency": "USD" }, "error_code": 0 } } ] }
              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456789",
      "to": "+6598765432",
      "server": "sms",
      "channel": "sms",
      "itime": 1701234567,
      "custom_args": {
        "order_id": "ORDER123",
        "user_id": "USER456"
      },
      "status": {
        "message_status": "sent",
        "status_data": {
          "msg_time": 1701234560,
          "message_id": "123456789",
          "current_send_channel": "CHANNEL_A",
          "template_key": "verify_code",
          "business_id": "1001"
        },
        "billing": {
          "cost": 0.005,
          "currency": "USD"
        },
        "error_code": 0
      }
    }
  ]
}
此代碼塊在浮窗中顯示

範例：訊息發送失敗

{ "total": 1, "rows": [ { "message_id": "123456790", "to": "+6598765433", "server": "sms", "channel": "sms", "itime": 1701234568, "status": { "message_status": "sent_fail", "status_data": { "msg_time": 1701234561, "message_id": "123456790", "current_send_channel": "CHANNEL_B", "template_key": "verify_code", "business_id": "1001" }, "error_code": 4001, "error_detail": { "message": "Invalid phone number" } } } ] }
              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456790",
      "to": "+6598765433",
      "server": "sms",
      "channel": "sms",
      "itime": 1701234568,
      "status": {
        "message_status": "sent_fail",
        "status_data": {
          "msg_time": 1701234561,
          "message_id": "123456790",
          "current_send_channel": "CHANNEL_B",
          "template_key": "verify_code",
          "business_id": "1001"
        },
        "error_code": 4001,
        "error_detail": {
          "message": "Invalid phone number"
        }
      }
    }
  ]
}
此代碼塊在浮窗中顯示

訊息通知

訊息通知是指系統級的業務事件或告警。用於提醒業務方關注服務運行狀態、餘額、範本審核等重要資訊，便於及時處理和風險預警。

事件標識 說明
insufficient_verification_rate 驗證率低於設定閾值
insufficient_balance 帳戶餘額不足
template_audit_result 範本審核結果的通知

範例

{ "total": 1, "rows": [{ "server": "otp", "itime": 1712458844, "notification": { "event": "insufficient_balance", "notification_data": { "business_id": "1744569418236633088", "remain_balance": -0.005, // 當前餘額； "balance_threshold": 2 // 告警閾值； } } }] }
              
              {
    "total": 1,
    "rows": [{
        "server": "otp",
        "itime": 1712458844,
        "notification": {
            "event": "insufficient_balance",
            "notification_data": {
                "business_id": "1744569418236633088",
                "remain_balance": -0.005,                    // 當前餘額；
                "balance_threshold": 2                       // 告警閾值；
            }
        }
    }]
}
此代碼塊在浮窗中顯示

訊息回應

訊息回應主要指與用戶或外部系統互動時的回調回應事件。

事件標識 說明
uplink_message 用戶透過簡訊等方式回覆的上行訊息內容

範例

{ "total": 1, "rows": [ { "server": "otp", "itime": 1741083306, "message_id": "0", "business_id": "0", "response": { "event": "uplink_message", "response_data": { "message_sid": "SM1234567890", "account_sid": "AC1234567890", "from": "+1234567890", "to": "+0987654321", "body": "Hello, it's time to struggle!" } } } ] }
              
              {
    "total": 1,
    "rows": [
        {
            "server": "otp",
            "itime": 1741083306,
            "message_id": "0",
            "business_id": "0",
            "response": {
                "event": "uplink_message",
                "response_data": {
                    "message_sid": "SM1234567890",
                    "account_sid": "AC1234567890",
                    "from": "+1234567890",
                    "to": "+0987654321",
                    "body": "Hello, it's time to struggle!"
                }
            }
        }
    ]
}
此代碼塊在浮窗中顯示

系統事件

系統事件涵蓋與帳號、範本、API 呼叫等相關的操作行為。便於對帳號登入、金鑰變更、API 呼叫等關鍵操作進行監控、審計和自動化處理。

事件標識 說明
account_login 帳號登入相關操作通知
key_manage 金鑰變更、管理等相關操作通知
msg_history 訊息歷史查詢相關操作通知
template_manage 範本新增、修改、刪除等操作通知
api_call API 介面呼叫相關操作通知

回調資料結構

外層結構

{ "total": 1, "rows": [ { // 系統事件物件 } ] }
              
              {
  "total": 1,
  "rows": [
    {
      // 系統事件物件
    }
  ]
}
此代碼塊在浮窗中顯示
欄位 類型 說明
total int64 本次回調包含的事件總數
rows array 系統事件物件陣列

系統事件物件

欄位 類型 說明
server string 固定為 "otp"
itime int64 事件發生時間戳（秒）
system_event object 系統事件內容

system_event 物件

欄位 類型 說明
event string 事件類型
data object 事件資料

data 物件

欄位 類型 說明
business_id string 業務 ID
org_id string 組織 ID
operator object 操作者資訊

operator 物件

欄位 類型 說明
email string 操作者信箱（如有）
api_key string API Key（如有）
ip_address string 操作 IP

請求結構

{ "total": 1, "rows": [ { "server": "otp", "itime": 1694012345, "system_event": { "event": "account_login", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "api_key": "api-xxxx", "ip_address": "1.2.3.4" }, "account_login": { "action": "login_success" } } } } ] }
              
              {
  "total": 1,
  "rows": [
    {
      "server": "otp",
      "itime": 1694012345,
      "system_event": {
        "event": "account_login",
        "data": {
          "business_id": "123",
          "org_id": "org-abc",
          "operator": {
            "email": "foo@example.com",
            "api_key": "api-xxxx",
            "ip_address": "1.2.3.4"
          },
          "account_login": {
            "action": "login_success"
          }
        }
      }
    }
  ]
}
此代碼塊在浮窗中顯示

帳號登入事件

欄位 類型 說明
action string 成功登入 / 登入失敗 / 登出
fail_reason string 登入失敗原因，僅 login_failed 時返回

範例

{ "event": "account_login", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "account_login": { "action": "login_success" } } }
              
              {
  "event": "account_login",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "account_login": {
      "action": "login_success"
    }
  }
}
此代碼塊在浮窗中顯示

範本管理事件

欄位 類型 說明
action string 建立範本 / 更新範本 / 刪除範本
template_id string 範本 ID
template_name string 範本名稱

範例

{ "event": "template_manage", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "template_manage": { "action": "update template", "template_id": "tmpl-456", "template_name": "Verification Code" } } }
              
              {
  "event": "template_manage",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "template_manage": {
      "action": "update template",
      "template_id": "tmpl-456",
      "template_name": "Verification Code"
    }
  }
}
此代碼塊在浮窗中顯示

金鑰管理事件

欄位 類型 說明
action string 枚舉值：
create api_key：建立 API Key
update api_key：更新 API Key
delete api_key：刪除 API Key
view api_secret：查看 API Secret
api_key string API Key
description string 描述（可選）

範例

{ "event": "key_manage", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "key_manage": { "action": "create", "api_key": "apikey-789", "description": "新建金鑰" } } }
              
              {
  "event": "key_manage",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "key_manage": {
      "action": "create",
      "api_key": "apikey-789",
      "description": "新建金鑰"
    }
  }
}
此代碼塊在浮窗中顯示

API 呼叫事件

欄位 類型 說明
api_path string 介面路徑
method string HTTP 方法

範例

{ "event": "api_call", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "api_key": "apikey-789", "ip_address": "1.2.3.4" }, "api_call": { "api_path": "/api/v1/messages/send", "method": "POST" } } }
              
              {
  "event": "api_call",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "api_key": "apikey-789",
      "ip_address": "1.2.3.4"
    },
    "api_call": {
      "api_path": "/api/v1/messages/send",
      "method": "POST"
    }
  }
}
此代碼塊在浮窗中顯示
Icon Solid Transparent White Qiyu
聯繫銷售