开发指南

简介

本指南用于指导开发者在自有服务器快速搭建 Webhook 消息接收服务，实时接收、处理易点易动推送的表单数据。文档包含推送方式、签名校验、响应规范及配套代码示例，适配各类开发语言与技术栈，助力完成易点易动与自有系统的数据打通。

开发步骤

推送方式

易点易动目前仅支持POST请求，请求中Header的Content-type类型为application/json。

POST http://example.com/hook?timestamp=1498586609&nonce=0f5ade
Headers:
{
  "X-YIDEA-Signature": "72d3162e-cc78-11e3-81ab-4c9367dc0958",
  "X-YIDEA-DeliverId": "sha1=7d38cdd689735b008b3c702edd92eea23791c5f6"
}
Body:
{
  "op": "Create",
  "data": {}
}

请求中还包含以下 Header 字段:

• X-YIDEA-DeliverId 为推送事件ID，每个推送事件的ID是唯一的（即使失败的推送触发了推送重试的机制时，仍可确保多次重试使用相同的事件ID）。可以通过该字段完成请求的去重，防止重复接收处理同一个事件。
• X-YIDEA-Signature 为签名内容，使用方式在下面的签名验证内容中会提到。

参数	说明
op	推送事件
data	具体数据内容

签名验证

为了防止 webhook 的接收服务器被第三方恶意攻击，用户在开发回调接口时，建议对回调请求进行签名校验，以确保回调请求来源来自于易点易动。Webhook会以POST的形式将内容以JSON格式发送给指定地址。

在界面上随机生成一个secret或者自己指定一个secret，并保存。这样，数据推送时就会把加密前的内容和通过secret加密后的内容一起推送到指定地址。

把http请求体字符串作为payload，将其和secret，请求参数里的 nonce、timestamp 按照 “{nonce}:{payload}:{secret}:{timestamp}” 的形式（用冒号分隔），组合为校验字符串 signature。

以 utf-8 编码形式计算 signature 的 sha-1 散列

将 signature 散列的十六进制字符串与 POST 请求 header 中的 ‘X-YIDEA-Signature’ 做比较，若比较结果相同，则通过签名验证；若比较结果不同，则无法通过检查

以Python为例：

def get_signature(nonce, payload, secret, timestamp):
content = ':'.join([nonce, payload, secret, timestamp]).encode('utf-8')
m = hashlib.sha1()
m.update(content)
return m.hexdigest()

@app.route('/callback', methods=['POST'])

def callback():
    payload = request.data.decode('utf-8')
    nonce = request.args['nonce']
    timestamp = request.args['timestamp']
    if request.headers['X-YIDEA-Signature'] != get_signature(nonce, payload, 'test-secret', timestamp):
    return 'fail', 401
        threading.Thread(target=handle, args=(json.loads(payload), )).start()
    return 'success'

响应规则

易点易动向对应目标服务器推送请求后，该服务器需在2秒内使用 2xx 作为响应的状态码进行响应，即认为数据推送成功。

如果在这段时间内没有接收到来自目标服务器的响应，则会尝试重新推送。

一次推送重试最多5次，如果单次推送连续重试5次均失败，则该次推送失败，此时会记录该数据在失败记录里。

代码示例

您可参考以下示例实现目标接口：

• C#
• Java
• Python

Webhook推送错误说明

接收到推送后需要返回给易点易动2xx表示推送接收成功。其他的返回结果则为返回信息错误，用户可以根据HTTP状态码自行定义推送错误的情况给易点易动的返回码，易点易动接受后，可在推送日志中显示出。