回调设置

最新更新:2023-03-07

概述

配置回调地址,用于接收 EngageLab OTP服务的「消息状态」和「消息通知」的数据回调给业务系统,并根据回调的信息进行数据统计、策略补发或者触发系统告警等。

  • 消息状态:用户发送一条 OTP 消息后,该消息的发送、送达、已读、验证等状态。
  • 消息通知:主要是系统事件,比如验证率过低、余额不足等事件。

配置回调

在【配置管理】-【回调设置】页面,点击“配置回调”,进行EngageLab OTP 服务的回调配置。

EngageLab OTP回调配置按钮

EngageLab OTP回调配置详情

按照上图所示,依次填写「回调描述」、「回调地址」、「用户名」、「Authorization」、「回调事件」等信息。

  • 勾选回调事件,在所选事件发生后,将信息推送到您设定的回调地址上。
  • 点击右侧消息状态和消息响应可以查看对应示例。

配置回调地址

配置回调地址时,EngageLab OTP 系统会发送一个 HTTP的 POST 请求到该地址,该地址对应的开发者服务在收到POST 请求之后,需要在 3 秒内响应 HTTP 状态码 200,否则系统会认为该地址无效。

  • 开发者服务只需要响应 HTTP 状态码 200,无需返回应答报文。

请求示例

假设配置的回调地址为 https://example.engagelabotp.callback.com ,我们会发送如下一个空报文给该地址,用curl命令表示如下:

curl -X POST https://example.engagelabotp.callback.com -d ''
          curl -X POST https://example.engagelabotp.callback.com -d ''

        
此代码块在浮窗中显示

响应示例

该回调地址对应的开发者服务在收到POST请求之后,只需要响应 200 HTTP状态码,示例如下:

HTTP/1.1 200 OK Content-Length: 0
          HTTP/1.1 200 OK
Content-Length: 0

        
此代码块在浮窗中显示

回调地址安全机制配置

  • 用户名设置

这是一个可选操作,如果设置了用户名,则必须填写密钥。

为了确保消息的来源身份是 Engagelab, 你可以选择对 POST 数据的来源进行安全认证.

配置用户名和秘钥后,EngageLab发过来的数据将带有HTTP Header: X-CALLBACK-IDX-CALLBACK-ID 的值为 timestamp={timestamp};nonce={nonce};username={username};signature={signature}

例如:

X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b
          X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b

        
此代码块在浮窗中显示

其中 timestamp 为回调消息的时间戳(标准),nonce为一个随机数,signature为签名信息,签名方法为:signature=HMAC-SHA256(secret, timestamp+nonce+username),

以下是计算signature的 python 代码示例:

import hashlib, hmac def verify(username, secret, timestamp, nonce, signature): return signature == hmac.new( key=secret, msg='{}{}{}'.format(timestamp, nonce, username), digestmod=hashlib.sha256).hexdigest()
          import hashlib, hmac
def verify(username, secret, timestamp, nonce, signature):
    return signature == hmac.new(
        key=secret,
        msg='{}{}{}'.format(timestamp, nonce, username),
        digestmod=hashlib.sha256).hexdigest()

        
此代码块在浮窗中显示
  • Authorization 设置

这是一个可选操作,如果您的回调地址需要对 EngageLab 的请求进行鉴权,请在此提供鉴权信息,EngageLab 将在请求时带上该 Authorization 。

回调请求体

回调事件触发时,EnageLab OTP 系统服务将会给回调地址发送数据。

「消息状态」请求示例

消息状态:

  • plan:计划发送
  • sent:已发送
  • sent_failed:发送失败
  • delivered:已送达
  • delivered_failed:送达失败
  • verified:已验证
  • verified_failed:验证失败
  • verified_timeout:验证超时
{ "total": 2, // 总数量 "rows": [{ // 数据 "message_id": "1742442805608914944", // 消息id "to": "+8615989574757", // 接收者 "server": "otp", // 服务,固定为otp "channel": "otp", // 通道,固定为otp "itime": 1704265712, // 该条数据的创建时间 "status": { // 消息状态 "message_status": "plan", // 消息状态,plan为计划发送,sent为已发送,sent_failed为发送失败 "status_data": { // 状态数据 "msg_time": 1704265712, // 消息发送时间 "message_id": "1742442805608914944", // 消息id "current_send_channel": "", // 当前发送通道,取值为sms、email、voice、whatsapp,当为plan时为空 "template_key": "auto_create_templateu25az170295320745", // 模板key "business_id": "100917676394736" // business id }, "error_code": 0 } }, { "message_id": "1742442805608914944", "to": "+8615989574757", "server": "otp", "channel": "otp", "itime": 1704265712, "status": { "message_status": "sent_failed", "status_data": { "msg_time": 1704265712, "message_id": "1742442805608914944", "current_send_channel": "whatsapp", "template_key": "auto_create_templateu25az170295320745", "business_id": "100917676394736" }, "error_code":5001, // 错误码 "error_detail":{ // 错误详情 "message":"sender config is invalid" // 错误信息 } } }] }
          {
    "total": 2,					// 总数量
    "rows": [{                  // 数据
        "message_id": "1742442805608914944",    // 消息id
        "to": "+8615989574757",            // 接收者
        "server": "otp",                    // 服务,固定为otp
        "channel": "otp",                   // 通道,固定为otp
        "itime": 1704265712,                // 该条数据的创建时间
        "status": {                         // 消息状态
            "message_status": "plan",       // 消息状态,plan为计划发送,sent为已发送,sent_failed为发送失败
            "status_data": {                // 状态数据
                "msg_time": 1704265712,     // 消息发送时间
                "message_id": "1742442805608914944",    // 消息id
                "current_send_channel": "",             // 当前发送通道,取值为sms、email、voice、whatsapp,当为plan时为空
                "template_key": "auto_create_templateu25az170295320745",    // 模板key
                "business_id": "100917676394736"        // business id
            },
            "error_code": 0
        }
    }, {
        "message_id": "1742442805608914944",
        "to": "+8615989574757",
        "server": "otp",
        "channel": "otp",
        "itime": 1704265712,
        "status": {
            "message_status": "sent_failed",
            "status_data": {
                "msg_time": 1704265712,
                "message_id": "1742442805608914944",
                "current_send_channel": "whatsapp",
                "template_key": "auto_create_templateu25az170295320745",
                "business_id": "100917676394736"
            },
            "error_code":5001,      // 错误码
            "error_detail":{    // 错误详情
                "message":"sender config is invalid"        // 错误信息
            }
        }
    }]
}

        
此代码块在浮窗中显示

「消息通知」请求示例

事件:

  • insufficient_balance: 余额低于告警阈值
{ "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                       // 告警阈值;
            }
        }
    }]
}

        
此代码块在浮窗中显示
在文档中心打开
Contact Sales