回调设置

概述

配置回调地址，用于接收 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-ID 。 X-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                       // 告警阈值；
            }
        }
    }]
}

此代码块在浮窗中显示