如何在 easySales 中设置 webhook:把订单、快递标签和库存变化发送到你的系统
在新订单、快递标签、发票和库存变化等 easySales 事件发生的同时,把它们发送到你自己的系统,并让订阅持续正常运行。
webhook 能做什么
webhook 会在 easySales 中发生某件事的同时通知另一个系统。当有新订单进来、生成了快递标签或库存发生变化时,easySales 会把详情发送到你指定的地址,这样你的 ERP、财务软件或网店就能立即做出反应,而不必每隔几分钟去查询一次 easySales。
登录后打开 easy-sales.com/webhooks 页面。页面上的每一行都是一个 订阅:一个事件,发送到一个地址。
先了解三点:
- 接收地址需要由你或你的开发人员搭建。 easySales 负责发送数据,该地址上的系统决定如何处理这些数据。
- 持续失败的订阅会自动关闭。 失败 100 次后,easySales 会停止发送并发邮件通知你。订阅不会自行重新开启。
- 订阅关闭期间的事件不会保留。 重新开启后,从那一刻起才恢复发送。
订阅事件
- 点击 Subscribe to webhook。
- 在 Url 中输入接收数据的地址。请使用 https 地址。
- HTTP method 保持为 POST。
- 在 Webhook 中选择事件。
- 在 Secret 中输入至少 24 个字符的密钥。你的系统用它来确认数据确实来自 easySales。
- 点击 Save。
订阅会显示在其事件名称下。如果要把同一事件也发送给第二个系统,请用另一个地址再订阅一次。同一个地址对每个事件只能添加一次。
| 事件 | 发送时机 |
|---|---|
| Order created | 任意渠道有新订单进来,或手动添加了订单。 |
| Order updated | 订单发生任何变化,例如状态、商品或地址。此事件发送频繁。 |
| Awb created | 通过 easySales 中的快递公司为订单生成了快递标签。 |
| Delivery status updated | 快递公司报告了某个包裹的新配送状态。 |
| Invoice created, Storno invoice created | 为订单开具了发票或红冲发票。 |
| Return created, Return updated | 创建了退货,或退货的状态、商品、备注、包裹或发票发生变化。 |
| Product created, Product updated | 添加或修改了商品,包括价格变化。 |
| Product stock updated | 商品库存发生变化。 |
| Category created / updated, Characteristic created / updated | 添加或修改了类目或属性。 |
| Products refresh requested, Stock refresh requested | 为网店请求刷新商品或库存。 |
| Ticket created, Ticket updated | 在 顾客 → 工单 中开始了与买家的对话,或已有对话发生变化。 |
| Account suspended, Account activated | easySales 账户被暂停或重新激活。 |
查看发送记录
每个订阅都会显示最近一次发送的事件是 Success 还是 Failed,以及发送时间。点击 More details... 查看该事件:
- Payload 是 easySales 发送的数据。
- Response 是你的地址返回的内容及其状态码。
- Attempt 2 of 3 | Next attempt: … 表示该事件发送失败,将会重新发送。Final attempt has been made 表示该事件不会再重试。
这里只显示每个订阅的最后一个事件。
修改、暂停或删除订阅
- Edit 可修改地址、HTTP 方法或密钥。要发送其他事件,请订阅该事件并删除旧订阅。
- Disable 暂停订阅,Enable 重新启动。暂停期间不会发送任何内容,这段时间的事件之后也不会补发。
- Unsubscribe 会立即删除订阅。
你的系统需要做什么
| 详情 | |
|---|---|
| 格式 | JSON,事件数据位于 payload 下,订阅 ID 和事件名称位于 webhook 下。 |
| 签名 | Signature 请求头包含用你的密钥对请求体计算出的 HMAC-SHA256。请按收到的原样请求体进行计算。 |
| 响应 | 3 秒内返回任意 2xx 状态。先响应,再处理数据。 |
| 证书 | https 地址必须使用有效的证书。 |
| 重试 | 每个事件最多尝试三次:第二次在第一次之后约 10 秒,第三次再过约 100 秒。 |
| 到达顺序 | 由于存在重试,事件可能不按顺序到达。请以 payload 中的数据为准,而不是到达时间。 |
订阅自动关闭时
每次失败的尝试都会计数:返回错误、3 秒内没有响应或证书有问题。失败 100 次后,订阅会被关闭,你会收到邮件“Webhook 已禁用”。邮件中的 查看 webhook 按钮会打开此页面。
- 修复接收地址上的问题。
- 点击该订阅的 Enable。
- 通过 easySales API 获取错过的变更,例如这段时间内被修改的订单。
📖
继续阅读
如何连接 easySales API:OAuth 客户端和个人访问令牌
为 easySales API 创建 OAuth 客户端和个人访问令牌,选择合适的授权类型和作用域,避免各个连接互相挤掉登录。
→
📖
继续阅读
如何通过 API 将自定义商店接入 easySales
通过 API 把任意自定义或尚未支持的商店平台接入 easySales:需要的两个凭据、推送产品与库存、送入订单,以及把变化取回去。
→
团队成员如何使用 webhook
团队成员需要 查看 webhook 权限才能打开该页面。有了这项权限,就可以添加、修改、暂停和删除订阅。
出现问题时
| 现象 | 处理方法 |
|---|---|
| 不再收到任何数据,订阅上显示 Enable | 订阅因多次失败已被关闭。修复地址,点击 Enable,然后通过 API 获取错过的变更。 |
| 最后一个事件显示 Failed | 打开 More details...,查看状态码和你的地址返回的内容。 |
| “The secret must be at least 24 characters.” | 输入至少 24 个字符的密钥。 |
| “The url has already been taken.” | 该地址已经在接收此事件。请改为编辑现有订阅。 |
| 收不到红冲发票 | 订阅 Storno invoice created;Invoice created 只涵盖普通发票。 |
| 接收系统被大量订单更新淹没 | Order updated 在每次变化时都会发送。请快速响应,并在后台处理数据。 |