Notification概览

概述

领科Cube API 出口（Webhook）系统采取RESTful API发送Notification API。
通知的内容为领科系统的events。
客户通过以下3种方式可以收到event通知

Sphere系统events发布后，客户在cube客户端或者autoflow API通过订阅autoflow event的 notitification API URL

经过客户的授权，FAE在Sphere为客户代为配置某些系统事件的notification API

客户在调用Cube API的某些异步接口时，临时配置了webhook地址，比如POST /order 的notification_callback_url 接收订单状态变更的通知。

Header结构

参数	必须	类型	示例值	说明	是否加入签名计算
x-lf-notification-version	必须	String	1.0	Notification api的版本标识	是
x-lf-algo	必须	String	HMAC-SHA1	算法标识，目前支持HMAC-SHA1。以后可以扩展, md5, sha256,等，默认为hmac-sha1	是
x-lf-signature	必须	String	{keyId}/{signature}	签名。有可能存在多对业务密钥。需要传keyid	是
x-lf-timestamp	必须	String	1683524066000	发送的时间戳，毫秒	是

算法

API出口携带领科定义的算法标识，其目的是加强通信双方的安全，防止报文篡改或非法发送。
接收Notification需要独立的Key。

HMAC-SHA1

计算signature步骤

Load notification key ( in raw hex)

组织报文：
2.1 POST 的body做JSON String encode, top-level key按字典排序（即数组不排序）=> sorted_message
2.2 加上头信息 {x-lf-notification-version}:{x-lf-algo}:{x-lf-timestamp}
例：

算法HMAC-SHA1（key=key_hex, data =message)

摘要做base64转换

x-lf-signature = {keyId}/{digest}
例：

验证signature步骤

根据x-lf-signature中的{keyId}, Load notification key

组织报文
2.1 POST 的body做JSON String encode, top-level key按字典排序（即数组不排序）=> sorted_message
2.2 加上头信息 {x-lf-notification-version}:{x-lf-algo}:{x-lf-timestamp}
例：

做HAMC-SHA1（key=key_hex, data =message)
注：key_hex指Cube页面中开发者模块的notification key value位置如下图所示

base64转换摘要

计算的摘要和接收到的x-lf-signature中的digest比较

推荐客户端应用在接收到校验失败的报文时，进行抛弃。

签名代码示例

Notification签名代码示例

重发机制

遇到下列情况，启动自动重发。自动重发3次（共4次），阶梯间隔：1，5， 10 （分钟）

领科内部超时(wait timeout, 等）或发送服务异常时

外部响应超时(read timeout, connection timeout等）

Status code >=500 时（2xx,3xx,4xx不需要重发）

概述#

Header结构#

算法#

HMAC-SHA1#

计算signature步骤#

验证signature步骤#

签名代码示例#

重发机制#