友好速搭

开放 API
使用说明 获取授权 全部 API 特殊 API 开放功能

智能通知

智能通知,依赖开放 API 中的 Webhook

以下内容包括:


什么是 Webhook

Webhook 允许第三方应用,监听站点中特定事件,当这些事件发生时,友好速搭将特定事件的参数,通过 HTTP 协议以 POST 方式通知指定的 URL。

通过 Webhook 获取数据,可以极大降低开发成本。例如,应用要获取新增商品或新订单信息,可通过 Webhook 接收通知信息,而无需轮询。


Webhook 事件

Webhook 支持以下事件:

名称 说明
products/create 商品创建
products/update 商品更新
products/delete 商品删除
orders/create 订单创建
orders/update 订单更新
orders/cancelled 订单取消
orders/request_refund 退单请求
orders/refunded 退单完成
orders/refuse_refund 拒绝退单请求
orders/paid 订单已付款
orders/delivered 订单已发货
orders/partially_delivered 订单已部分发货
orders/achieved 订单完成
payments/create 支付创建
payments/update 支付更新
payments/unusual 支付异常
shipments/create 配送创建
shipments/update 配送更新
shipments/delete 配送删除
customers/create 顾客创建
customers/update 顾客更新
customers/delete 顾客删除
shop/update 店铺更新

配置 Webhook

通过开放 API 创建 Webhook。 不同于客户端的跳转,Webhook 是在友好速搭服务器端,访问指定的 URL。所以,使用的 URL 不能包括以下情况:

  • localhost
  • 虚假的域名,例如 www.example.com
  • 友好速搭的相关域名(例如 youhaosuda.com 或 *.v.youhaosuda.com)

对于测试 Webhook 有相关的在线免费服务工具,推荐以下:


响应 Webhook 通知

在店铺创建 Webhook 后,当事件被触发时,友好速搭会立刻通过HTTP POST访问指定 URL。Webhook 通知是以 post 形式发送的 JSON ,放在请求的 body 里,内容是事件对应的对象。

在接收到友好速搭的 Webhook 请求后,需要在 10 秒内返回 HTTP 200 的状态码。否则,友好速搭认为 Webhook 通知失败,会启用重试机制。


Webhook 重试机制

友好速搭发送的 Webhook 通知,首次是即时推送,但如果在 10 秒内,没得到 HTTP 200 的状态码返回,该条通知,会启用重试机制,重试至多 7 次,间隔分别是:2min、10min、10min、1h、2h、6h、15h。

在开发应用时,涉及 Webhook 的处理,务必确保及时响应。对于一个数据对象,在一段时间内,可能有不同的操作,而 Webhook 重试的通知,使用的参数,很可能已经是历史数据,处理重试的通知,会增加应用的业务复杂度。


验证 Webhook 通知来源

在应用中,可以通过计算并核对数字签名,来验证 Webhook 的请求,是否来自友好速搭。

来自友好速搭的 Webhook,都包含名为X-YHSD-HMAC-SHA256的 HTTP 头,它是使用店铺的Webhook Token,对传输的数据进行SHA256加密获得。

为避免第三方恶意伪造数据,强烈建议在应用中,强制检测 Webhook 的签名。不同编程语言的验证示例如下:

require 'rubygems'
require "openssl"
require "base64"
require "sinatra"

# 用于加解密的 Webhook 密钥
WEBHOOK_TOKEN = '906155047ff74a14a1ca6b1fa74d3390'

helpers do
  def verify_webhook(data, hmac_header)
    digest  = OpenSSL::Digest::Digest.new('sha256')
    calculated_hmac = Base64.encode64(OpenSSL::HMAC.digest(digest, WEBHOOK_TOKEN, data)).strip
    calculated_hmac == hmac_header
  end
end

post '/' do
  request.body.rewind
  data = request.body.read
  verified = verify_webhook(data, env["HTTP_X_YHSD_HMAC_SHA256"])

  puts "Webhook verified: #{verified}"
end
友好速搭,让商业更简单
0元开始
联系客服