Webhook 推送

亚马逊关于你店铺的通知——商品、价格与报价、订单、库存、销售、财务、账户健康等——推送到你的团队聊天群,或以签名 JSON 推送到你自己的系统。

TL;DR

  • 你的 listing、价格、报价、订单、库存或账户发生变化时,亚马逊会通知 SellerSheet。Webhook 把每条消息转发出去:在团队聊天群(飞书 / Lark、Slack、Microsoft Teams、企业微信、钉钉)里显示为卡片,或通过 HTTPS 以签名 JSON 推送到你自己的系统。
  • 可从 23 类亚马逊通知中选择,按组列出;新建的 Webhook 默认勾选六类。每小时指标和逐条变动的通知只能推送到 HTTPS。
  • 在 设置 → Webhook 推送 → 添加 Webhook 中设置(工作区所有者或管理员),然后点击 发送测试。
  • 所有套餐每月免费送达 500 条消息。 超出部分每条送达的消息从积分中扣费。测试、发送失败和未发送的消息从不计费。

Webhook 能做什么

你的卖家账户发生变化时,亚马逊会发出通知:listing 被屏蔽或恢复可购买、你的报价因价格失去推荐报价(Featured Offer)资格、有人修改了你品牌的详情页、其他卖家跟卖了你的 ASIN、买家申请取消订单、FBA 库存售罄、你的账户出现风险。Webhook 把这些消息送到你工作的地方:

  • 团队聊天群。 每分钟最多一张卡片,按店铺分组,并附上亚马逊自己的字段名,群里的人——或群里的 AI 智能体——可以直接据此处理。
  • 你自己的系统。 ERP、数据库或你自己的代码以签名 JSON 收到每条消息,里面原样带着亚马逊的通知。

每条消息只用亚马逊发来的内容组成;SellerSheet 不会为此另外调用亚马逊接口补充信息。亚马逊是唯一的事实来源。

通知如何送达。卖家账户有变化时——Listing、价格与报价、订单、库存、账户健康、报告——亚马逊发出通知。SellerSheet 只向亚马逊订阅你的 Webhook 需要的通知,把一分钟内的变化合成一张群聊卡片,每个 HTTPS 请求都带签名;所有套餐每月 500 条免费。它推送到你的团队群聊——飞书、Slack、Teams、企业微信或钉钉,每分钟最多一张卡片,颜色取最严重的变化——或以带签名的 JSON 推送到你自己的系统,每次最多 100 条消息,内含亚马逊的原始通知。某个通知 24 小时没有 Webhook 需要,SellerSheet 就在亚马逊取消订阅

添加 Webhook

你需要是工作区的所有者或管理员。Webhook 属于你当前所在的工作区:请先切换到正确的工作区。

获取地址

按下方推送目标中对应目标的步骤复制地址。推送到 HTTPS 时,还要自己生成一个签名密钥。

添加 Webhook

在 SellerSheet 应用中打开 设置 → Webhook 推送 → 添加 Webhook:

  • 推送方式:飞书、Slack、Microsoft Teams、企业微信、钉钉或 HTTPS。之后不能修改。
  • Webhook 名称:在工作区内唯一,例如 ERP 对接 或 运营群。
  • 地址;目标支持时,填写 签名密钥。
  • 仅聊天应用:语言——中文或 English,群里卡片使用的语言。新建时默认跟你使用应用的语言,之后随时可以修改。见卡片语言。
  • 通知与店铺:哪些通知、哪些店铺。最初的六类通知默认已勾选。见选择通知与店铺。
  • 包括未连接到 SellerSheet 的站点(默认打开)。
  • 仅聊天应用:竞争报价:仅在卖家或购物车赢家变化时推送(默认打开)。只有价格变化的消息会被过滤——不推送、不计费。
  • 勾选按消息计费的确认框,然后点击 创建 Webhook。

只有当组织能为下一条消息付费时——本月还有免费消息,或有积分——才能创建 Webhook 或重新开启它。

发送测试

在 Webhook 所在行(或它的编辑面板里)点击 发送测试。目标会收到一个虚构店铺的示例消息,这个 Webhook 接收的每类通知各一条;聊天应用里卡片标题以“· 测试”结尾(语言为 English 的 Webhook 是“· test”)。如果目标拒收,页面会显示它的回复——见常见问题排查。测试消息从不计费。

之后,列表会显示每个 Webhook 的 推送状态、本月消息(已送达的消息数)和 最近推送。编辑 Webhook 可以修改除推送方式以外的所有设置;地址或密钥留空则保留原值,启用推送 用来开启或关闭这个 Webhook。删除 Webhook 会立即停止推送;它的推送记录保留 30 天。每个工作区最多保留 10 个 Webhook。

地址和密钥加密保存,之后不会再显示:列表只显示地址的最后四个字符。

推送目标

目标收到什么签名密钥
飞书 / Lark每分钟最多一张互动卡片可选——飞书的签名校验
Slack每分钟最多一条消息—
Microsoft Teams每分钟最多一张 Adaptive Card—
企业微信每分钟最多一条 markdown 消息—
钉钉每分钟最多一条 markdown 消息可选——钉钉的“加签”
HTTPS签名 JSON,每个请求最多 100 条消息必填

启用了自定义关键词的聊天机器人需要添加关键词 SellerSheet——每张卡片的标题都包含它。设置了 IP 白名单的机器人或接收端点需要放行 SellerSheet 的 IP 地址:请联系客服获取。

飞书 / Lark

  1. 在群里打开 设置 → 群机器人 → 添加机器人 → 自定义机器人。
  2. 复制它的 webhook 地址:https://open.feishu.cn/open-apis/bot/v2/hook/…(Lark:https://open.larksuite.com/open-apis/bot/v2/hook/…)。
  3. 可选安全设置:打开签名校验并把密钥粘贴到 签名密钥,或打开自定义关键词并填写关键词 SellerSheet。

Slack

  1. 在你的 Slack 应用中打开 Incoming Webhooks。
  2. 点击 Add New Webhook 并选择频道。
  3. 复制地址:https://hooks.slack.com/services/…

Microsoft Teams

  1. 在频道中打开 工作流。
  2. 选择 “收到 webhook 请求时发布到频道” 并完成工作流设置。
  3. 复制工作流给出的地址;它的域名以 logic.azure.com 或 powerplatform.com 结尾。

企业微信

  1. 在群里打开 ··· → 群机器人 → 添加。
  2. 复制它的 webhook 地址:https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=…

企业微信能接收的消息比其他应用短,所以它的卡片在“+N more”之前能显示的行数更少。

钉钉

  1. 在群设置中打开 机器人 → 添加机器人 → 自定义。
  2. 在安全设置中选择 加签,把以 SEC 开头的密钥粘贴到 签名密钥;或选择自定义关键词 SellerSheet。
  3. 复制地址:https://oapi.dingtalk.com/robot/send?access_token=…

HTTPS

  1. 准备一个接收端点:接受带 JSON 请求体的 POST,地址是公网可访问的 https:// 地址(端口 443)。私有和内网地址会被拒绝,也不会跟随重定向。每次请求前都会重新检查地址。
  2. 自己生成一个足够长的随机签名密钥(例如 openssl rand -hex 32 的输出),粘贴到 签名密钥,并在你的接收端保存一份。
  3. 在接收端校验每个请求的签名,10 秒内返回任意 2xx,然后再处理消息。

收到的内容:HTTPS 请求体。

选择通知与店铺

通知与店铺 表格按组列出亚马逊提供的全部通知:每行一类通知,每列一个店铺。

  • 勾选 所有店铺 会接收工作区的所有店铺,包括之后连接的店铺;也可以逐个勾选店铺。
  • 新建的 Webhook 默认勾选最初的六类通知——商品问题、商品状态、品牌内容、价格健康、竞争报价和账户健康——并勾选所有店铺;只有品牌内容默认只勾选一个店铺。其他通知按需勾选。
  • 灰色的行不能勾选,并注明原因:以数据形式进入你的报表,不作为 Webhook 推送(亚马逊广告)、暂未开放(物流追踪节点),或推送到聊天群时的 仅限 HTTPS。见通知类型。
  • 高频:推送到 HTTPS 时,每小时指标和每次变动一条消息的通知带有这个标记。店铺繁忙时每天可能有很多条,每条送达的消息都计入用量。
  • 有些通知只针对部分站点: FBA Onsite 货件只在巴西发送(仅限 BR)。没有巴西站点的店铺不能勾选它。所有店铺 始终可以勾选:亚马逊不会为其他店铺发送。
  • 每个店铺各一份: 品牌内容 和 商品类型定义,亚马逊会给同一卖家的每个店铺各发一份,内容相同。只选一个店铺,每次变化只收到一次;选多个就每个店铺各收到一份,表格会提醒你。
  • 不涉及具体站点的消息——账户健康、报告、上传文件、Data Kiosk 查询、多渠道配送订单、自发货库存数量、外部仓发货——会发给在该卖家任一店铺上接收这类通知的 Webhook。
  • 聊天群不接收仅限 HTTPS 的通知。 如果在选择聊天应用之前已勾选了这类通知,表单会提示有几项不会发送;它们也不会保存。
  • 包括未连接到 SellerSheet 的站点:有些通知覆盖你整个卖家账户,所以消息可能涉及你没有连接到 SellerSheet 的站点。打开时,这些消息照常送达,卡片上标注“(not connected)”,HTTPS 中为 "connected": false。关闭即可不接收。

亚马逊订阅跟随你的 Webhook

SellerSheet 只向亚马逊订阅你的 Webhook 需要的通知,不多订:

  • 每个卖家账户、区域和通知类型只有一个亚马逊订阅,供所有 Webhook 共用。新建的 Webhook 如果接收的店铺和通知已经订阅,会立即开始收到消息。
  • 还没有任何 Webhook 需要的通知,会在约一分钟内向亚马逊订阅。
  • 某个店铺的某类通知连续 24 小时没有任何开启中的 Webhook 需要时,SellerSheet 会在亚马逊取消订阅。之后若有 Webhook 再次需要,会在约一分钟内重新订阅。取消订阅期间亚马逊发布的消息不会送达。
  • 店铺单元格上的小标记会说明即将结束的订阅(亚马逊订阅将于 … 结束,除非有 Webhook 重新接收它。)或被亚马逊拒绝的订阅:该卖家的这类通知已被其他应用订阅;此通知需要的权限不在该店铺的授权范围内(SellerSheet 每天重试一次;若一直失败,请重新授权店铺或联系客服);或 SellerSheet 会再次尝试。

通知类型

Webhook 推送页面列出 SellerSheet 能推送的亚马逊 Selling Partner API 通知,以及亚马逊广告的两个 Marketing Stream 数据集,分为 9 组:

  • 已上线:23 类通知。 最初的六类在新建 Webhook 时默认勾选(下表标为“默认”)。
  • 暂未开放:物流追踪节点。 亚马逊要求先逐个登记货件。
  • 亚马逊广告:不是 Webhook。 广告表现以数据形式进入你的报表(Amazon Marketing Stream),所以这两行在任何推送方式下都是灰色的。

推送到聊天群时,仅限 HTTPS 的通知也是灰色的,并注明原因。推送到 HTTPS 时这些行可以勾选,其中每小时指标和每次变动一条消息的通知带有 高频 标记。

不提供:亚马逊巴西和墨西哥的三类税务发票通知。亚马逊只允许获得税务开票角色的应用订阅,SellerSheet 的应用没有这个角色。

商品与 Listing

通知告诉你什么上线推送方式
商品问题listing 的问题发生变化:当前生效的严重程度和处置动作,或问题已全部清除。从不包含问题的具体文字。已上线(默认)HTTPS、聊天群
商品状态listing 变为可购买或不可购买、能否被搜索到,或已删除。已上线(默认)HTTPS、聊天群
品牌内容你品牌下某个商品目录条目的属性变化——标题、五点描述、图片等。每个店铺各一份。已上线(默认)HTTPS、聊天群
商品类型变更某个 ASIN 的商品类型变了;它的 listing 需要填写的内容可能随之变化。已上线HTTPS、聊天群
自发货库存数量某个 SKU 的自发货库存数量变化。已上线仅限 HTTPS:每次变动一条消息
商品类型定义亚马逊发布某个站点商品类型定义的新版本,并列出新增的商品类型。每个店铺各一份。已上线仅限 HTTPS:供你自己的程序使用

价格与报价

通知告诉你什么上线推送方式
价格健康你的报价因价格无法成为推荐报价,附带亚马逊的参考价格。只有 ASIN,没有 SKU。已上线(默认)HTTPS、聊天群
竞争报价有其他卖家的在售 ASIN 上报价变化:购物车、价格、卖家。已上线(默认)HTTPS、聊天群
企业购报价同上,针对 ASIN 上的企业购(B2B)报价。已上线仅限 HTTPS:每次变动一条消息
费用促销亚马逊为你提供费用促销:内容、时间和折扣。已上线HTTPS、聊天群

订单与配送

通知告诉你什么上线推送方式
订单变更订单状态变化,或买家提出变更,例如取消订单。已上线HTTPS、聊天群
多渠道配送订单多渠道配送订单的状态、包裹和物流单号。已上线HTTPS、聊天群
FBA Onsite 货件(巴西)亚马逊为订单创建或取消货件。仅限 BR。已上线HTTPS、聊天群
外部仓发货你自己的配送仓里某个货件的状态变化。已上线HTTPS、聊天群
物流追踪节点货件的承运商追踪节点。暂未开放HTTPS、聊天群

库存

通知告诉你什么上线推送方式
FBA 库存某个 SKU 的 FBA 库存数量变化——可售、入库中、预留、不可售——按站点列出。已上线仅限 HTTPS:每次变动一条消息
每小时库存每小时:高可用库存的件数。已上线仅限 HTTPS:每小时指标

销售与流量

通知告诉你什么上线推送方式
每小时销售每小时:订购件数和销售额。已上线仅限 HTTPS:每小时指标
每小时页面浏览每小时:详情页浏览量。已上线仅限 HTTPS:每小时指标

财务

通知告诉你什么上线推送方式
交易一笔交易记入你的账户:类型、金额和相关编号,例如订单号。已上线仅限 HTTPS:每次变动一条消息

账户状况

通知告诉你什么上线推送方式
账户健康卖家账户状态在正常、有风险和已停用之间变化。已上线(默认)HTTPS、聊天群

报告与数据(开发者)

通知告诉你什么上线推送方式
报告完成报告请求处理结束——完成、已取消或失败——附报告 ID 和文档 ID。已上线仅限 HTTPS:供你自己的程序使用
上传文件处理完成上传文件(feed)处理结束——完成、已取消或失败——附结果文档 ID。已上线仅限 HTTPS:供你自己的程序使用
Data Kiosk 查询完成Data Kiosk 查询结束,附数据文档或错误文档 ID。已上线仅限 HTTPS:供你自己的程序使用

亚马逊广告(Marketing Stream)

数据集内容推送方式
广告表现(每小时)每小时:各广告活动的曝光、点击、花费、转化和销售额。以数据形式进入你的报表,不是 Webhook—
转化商品(每天)每天:看到广告后购买的商品。以数据形式进入你的报表,不是 Webhook—

每条消息的 summary 都带一行可读的 text 和一个 severity,以及该通知自己的字段。每类通知在亚马逊的代码(messageType)和字段:Webhook 消息格式。

你会看到的情况

  • 消息何时到达。 商品问题和商品状态通常在变化后约 11–19 分钟到达;价格健康和品牌内容约一分钟内到达。默认的六类里,竞争报价通常量最大。
  • 删除后的“问题已清除”。 删除一个 SKU 约 20 分钟后,亚马逊会清除它的问题;这条消息和其他消息一样送达。
  • 最后一个竞争者离开。 只有 ASIN 上有其他卖家时亚马逊才会通知,所以最后一个卖家离开时不会有消息。
  • 报告完成也包括 SellerSheet 自己的报告: 即 SellerSheet 为同步你店铺数据而请求的报告,每天很多个。
  • 把消息当作确认。 你修改 listing、价格或品牌内容后,消息会告诉你亚马逊已经生效。

严重程度与颜色

severity卡片颜色何时
critical红色listing 被屏蔽或其商品目录条目被移除;账户被停用;订单无法配送
warning橙色其他 listing 问题;listing 不可购买或已删除;商品类型变更;价格健康;其他卖家拿到了购物车;账户有风险;缺货(自发货或 FBA);买家申请取消或订单已取消;配送订单部分完成或已取消;货件已取消;报告、上传文件或 Data Kiosk 查询被取消或失败
info蓝色其他情况——例如品牌内容、你持有购物车或无人持有时的竞争报价、每小时指标、交易、费用促销、已完成的报告
recovery绿色问题已清除;listing 恢复可购买;账户恢复正常;多渠道配送订单完成

聊天卡片显示什么

名为 Amazon alerts 的飞书群里,群机器人发来的五张 SellerSheet Webhooks 卡片,从早到晚:红色——listing 被屏蔽、不可购买;橙色——价格健康和买家申请取消订单;橙色——其他卖家拿到购物车;蓝色——品牌内容有修改;绿色——listing 恢复可购买、问题已清除
飞书 / Lark · 点击放大
同样五张卡片在 Slack 频道 #amazon-alerts 中:每张有加粗标题,彩色侧边条内是店铺的各行内容和页脚
Slack · 点击放大

语言选 中文 的 Webhook,卡片是这样的(上面两张图里是语言选 English 的卡片):

SellerSheet Webhooks · myStore · 3 条消息
myStore-US (3)
• 商品问题 · SKU SKU-EXAMPLE-01 · B0EXAMPLE01 — 商品不可购买(被禁止显示) · Severities=ERROR · EnforcementActions=LISTING_SUPPRESSED
• 商品状态 · SKU SKU-EXAMPLE-02 · B0EXAMPLE02 — 可购买 · Status=BUYABLE,DISCOVERABLE
• 竞争报价 · B0EXAMPLE05 — 1 个其他卖家:A2EXAMPLEOTHER 19.99 USD FBM,购物车,好评率 95%(120 条) · 你 21.49 USD FBA,好评率 99%(812 条) · OfferChangeType=External · BuyBoxPrice=19.99 USD · NumberOfOffers=new Merchant 1,new Amazon 1
亚马逊 02:28 发送(02:14 变更)GMT-7 · 各项含义
  • 每分钟最多一张卡片。 第一条消息开启一个一分钟的窗口;窗口内到达的所有消息都放在同一张卡片上。(窗口累计到 2,000 条消息时会立即发出卡片。)
  • 标题: SellerSheet Webhooks、店铺名称(最多两个,否则显示店铺数)和消息数。
  • 颜色: 取卡片上最严重的严重程度。
  • 分组: 每个店铺 ref 一组,例如 myStore-US;“(未连接)”标注你没有连接的站点(English 卡片上是“(not connected)”)。
  • 每一行: 通知类型、SKU 和 ASIN(ASIN 链接到该站点的商品页),通俗说明,然后是亚马逊自己的字段名和值,格式为 Field=VALUE,群里的 AI 智能体可以直接依据这些代码处理。竞争卖家的 ID 链接到它的店铺页,店铺页上能看到名称;最多列出 5 个卖家,之后显示“另 N 个”。
  • 重复: 相同的消息——同一店铺、通知类型、文字和变化时间——合并为一行,以 ×N 结尾。每一条都已送达,也都计数。
  • 长卡片: 超过 40 行或聊天应用的大小上限后,卡片以“另有 N 条 — 查看推送记录”结尾,链接到这个 Webhook 的推送记录。卡片承载的每条消息,无论是否显示,都已送达。
  • 底部: 亚马逊发出消息的时间,括号里是变化发生的时间(若是更早的一天则带日期),按第一个店铺所在站点的时区;然后是 各项含义,链接到本节说明。

卡片语言

每个聊天类 Webhook 都有 语言:中文或 English。SellerSheet 写在卡片上的字都跟着它——消息数、通知类型名、通俗说明、“(未连接)”、“另有 N 条”和底部;中文卡片底部的 各项含义 打开本节的中文版。亚马逊自己的字段名和值(Severities=ERROR、competitivePriceThreshold=24.99 USD)、SKU、ASIN、卖家 ID 和价格保持亚马逊发来的原样,所以群里的 AI 智能体无论卡片是哪种语言,读到的都是同一套代码。

HTTPS 没有语言选项:JSON 里原样带着亚马逊的通知。

HTTPS 请求体

每个请求都是 POST,Content-Type: application/json,并带以下请求头:

请求头值
X-SellerSheet-Webhook-IdWebhook 的 ID
X-SellerSheet-Delivery-Id这次推送的 ID——每次重试都相同
X-SellerSheet-Timestamp这次尝试发出时的 Unix 秒数
X-SellerSheet-Signaturesha256= 加上以你的签名密钥为 key、对“时间戳、一个 .、原始请求体”计算的十六进制 HMAC-SHA256
X-SellerSheet-Test发送测试 时为 true,否则为 false

请求体是一次推送(delivery):最多 100 条消息,不超过 1 MB。积累到 100 条消息,或第一条消息到达 2 秒后,就会发出请求。下面是包含一条消息的示例,数值均为虚构:

{
  "deliveryId": "dlv_8f3a1c9e2b7d4e6fa0b1c2d3e4f5a6b7",
  "webhookId": "0c6f2a8e-4d1b-4e7a-9b35-6e8d2f1a4c90",
  "organizationId": "7b2e9c41-0d3a-4f6b-8e15-9c2a4d6f8b30",
  "sentAt": "2026-10-27T09:28:33Z",
  "attempt": 1,
  "schemaVersion": 1,
  "messages": [
    {
      "messageId": "5c0e8f4a-2b7d-4e91-a3c6-000000000001",
      "messageType": "LISTINGS_ITEM_ISSUES_CHANGE",
      "fingerprint": "sha256:af6e358a51bec4bc1275fba29469312dce87aa4609a42c42564a35c8c190d1a5",
      "store": {
        "storeId": "3f6c2a9e-5b1d-4c8e-9a7f-2d4e6b8c0a11",
        "ref": "myStore-US",
        "sellerId": "A1EXAMPLESELLER",
        "marketplaceId": "ATVPDKIKX0DER",
        "countryCode": "US",
        "connected": true
      },
      "eventTime": "2026-10-27T09:14:03Z",
      "publishTime": "2026-10-27T09:28:30Z",
      "receivedAt": "2026-10-27T09:28:32Z",
      "summary": {
        "text": "SKU SKU-EXAMPLE-01 (B0EXAMPLE01) on US: Listing not buyable (suppressed) · Severities=ERROR · EnforcementActions=LISTING_SUPPRESSED",
        "severity": "critical",
        "sku": "SKU-EXAMPLE-01",
        "asin": "B0EXAMPLE01",
        "severities": ["ERROR"],
        "enforcementActions": ["LISTING_SUPPRESSED"],
        "cleared": false
      },
      "amazon": {
        "notificationType": "LISTINGS_ITEM_ISSUES_CHANGE",
        "notificationVersion": "1.0",
        "payloadVersion": "2023-12-13",
        "eventTime": "2026-10-27T09:14:03.000Z",
        "notificationMetadata": {
          "ApplicationId": "amzn1.sp.solution.00000000-0000-4000-8000-000000000000",
          "SubscriptionId": "9d4b7e2a-6c1f-4a85-b3e0-000000000001",
          "PublishTime": "2026-10-27T09:28:30.000Z",
          "NotificationId": "5c0e8f4a-2b7d-4e91-a3c6-000000000001"
        },
        "payload": {
          "Sku": "SKU-EXAMPLE-01",
          "Asin": "B0EXAMPLE01",
          "SellerId": "A1EXAMPLESELLER",
          "MarketplaceId": "ATVPDKIKX0DER",
          "Severities": ["ERROR"],
          "EnforcementActions": ["LISTING_SUPPRESSED"]
        }
      }
    }
  ]
}

怎么读:

  • 推送本身。 deliveryId 在同一请求的每次重试中都相同;attempt 是第几次尝试(1 到 3)。webhookId 和 organizationId 分别是 Webhook 和你的工作区。schemaVersion 为 1。
  • messageId 是亚马逊的 NotificationId:一条亚马逊消息。messageType 是亚马逊的通知类型。schemaVersion 1 内可能新增类型:遇到不认识的类型,按它的 summary.text 处理,或直接跳过。
  • fingerprint 对亚马逊再次发布的同一变化保持相同——见重复消息。
  • store 是你的店铺和这条消息涉及的站点:ref 是店铺 ref(myStore-US);对于你没有连接的站点,connected 为 false。
  • 时间均为 UTC:eventTime 是变化发生的时间,publishTime 是亚马逊发出的时间,receivedAt 是 SellerSheet 收到的时间。
  • summary 是 SellerSheet 的解读:一行可读的 text、severity、sku、asin,以及该通知类型自己的字段。
  • amazon 是亚马逊的通知,每个值都与亚马逊发送的完全一致——这是事实来源。亚马逊有些通知的键用 PascalCase,有些用 camelCase:两种写法都要能读。
  • 每个键都会发送;没有值的键为 null。对象不封闭:遇到不认识的键直接忽略。

请求体的 JSON Schema(2020-12)发布在 sellersheetai.com/schemas/webhooks-v1.json,每类通知的示例推送在 sellersheetai.com/schemas/webhooks-v1-samples.json。所有字段、类型和示例:Webhook 消息格式。

发送测试 的请求带 X-SellerSheet-Test: true,以及虚构店铺 SampleStore 的示例消息,这个 Webhook 接收的每类通知各一条。像其他请求一样回复它,但不要据此执行任何操作。

校验签名

信任一个请求之前先校验它:

  1. 读取原始请求体字节,在任何 JSON 解析之前。
  2. 时间戳与你的时钟相差超过 5 分钟就拒绝——被重放的请求会失败。每次重试都带新的时间戳,所以重试能通过。
  3. 以签名密钥为 key,对 时间戳 + "." + 原始请求体 计算 HMAC-SHA256,用常量时间比较 sha256=<hex> 与请求头。
  4. 校验通过就立即返回 2xx,之后再处理消息;校验失败返回 401。
verify.py
import hashlib, hmac, time

def verify(secret: str, headers, raw_body: bytes, tolerance: int = 300) -> bool:
    timestamp = headers.get("X-SellerSheet-Timestamp", "")
    signature = headers.get("X-SellerSheet-Signature", "")
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > tolerance:
        return False
    mac = hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256)
    return hmac.compare_digest("sha256=" + mac.hexdigest(), signature)
verify.mjs
import { createHmac, timingSafeEqual } from "node:crypto";

// headers: lower-case names, as Node gives them; rawBody: a Buffer of the body as received
export function verify(secret, headers, rawBody, tolerance = 300) {
  const timestamp = headers["x-sellersheet-timestamp"] ?? "";
  const signature = headers["x-sellersheet-signature"] ?? "";
  if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > tolerance) return false;
  const mac = createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest("hex");
  const expected = Buffer.from(`sha256=${mac}`);
  const given = Buffer.from(signature);
  return expected.length === given.length && timingSafeEqual(expected, given);
}

在 Express 中,用 express.raw({ type: "application/json" }) 读取该路由的原始请求体;在 Flask 中用 request.get_data()。

重试、暂停与恢复

  • 重试。 每次推送立即尝试一次,20 秒后和 90 秒后各再试一次——deliveryId 不变,attempt 递增。每次尝试最多等待 10 秒回复。
  • 什么算尝试失败: 回复不是 2xx(包括重定向——不会跟随),10 秒内没有回复,连接不上,或聊天应用在回复中表示拒收(例如飞书的 code、企业微信的 errcode)。
  • 推送失败。 三次尝试都失败时,这次推送的消息记为 发送失败:不计费,也不会再发送。
  • 暂停。 连续 3 次推送失败后,Webhook 变为 已暂停(连续失败),组织的所有者和管理员会收到一封邮件。中间只要有一次送达,计数就重新开始。
  • 恢复。 Webhook 推送页面会为暂停的 Webhook 显示一条横幅。恢复推送 会先发送一条测试消息,目标接受后才重新开启;否则保持暂停,并显示目标的回复。
  • 暂停或关闭期间,不发送也不计费。期间到达的消息在推送记录中记为 未发送,之后也不会补发。
  • 已暂停(积分不足)。 见计费与用量:它会自动恢复。
  • 太慢。 如果某个 HTTPS 接收端点积压了 2,000 条消息,发给它的新消息会立即记为失败(“the webhook answers too slowly”),而不会拖慢其他 Webhook。
  • 要自己停止一个 Webhook,编辑它并取消勾选 启用推送。

重复消息与 messageId

亚马逊是事实来源:SellerSheet 送达亚马逊发出的每一条消息,包括亚马逊自己的重复发送,中途不丢弃任何消息。

  • 重试会重复一次推送。 如果你的接收端已经处理了某次推送但回复太晚,下一次尝试会带来相同的 deliveryId 和相同的消息。把处理过的 messageId 保留一两天,遇到已有的就丢弃。
  • 亚马逊有时会把同一变化再发布一次,作为一条新消息——新的 messageId,相同的 eventTime。它的 fingerprint 相同,所以如果每个变化只想处理一次,就比较 fingerprint。在聊天卡片上,这类重复合并为一行 ×N。
  • 品牌内容 和 商品类型定义:你勾选的每个店铺各收到一份——只勾选一个店铺,每次变化只收到一次。
  • 竞争报价走 HTTPS 时每条都会送达,sellersChanged 和 buyBoxWinnerChanged 说明与上一条消息相比,ASIN 上的卖家或购物车赢家是否变化;只想要这些变化时,按这两个字段过滤。

计费与用量

  • 每月免费送达 500 条消息,每个组织、所有套餐都一样。每月 1 日(UTC)重新计数。
  • 超出 500 条后,每条送达的消息从组织的积分中扣费,价格显示在 Webhook 推送页面上。套餐与积分:套餐与价格和账单与积分。
  • 一条消息送达一个 Webhook 计为一条。 被两个 Webhook 接收的消息计两次。聊天卡片承载的每条消息都计数,包括 ×N 合并的行和“+N more”。
  • 从不计费: 测试消息、发送失败的消息、未发送的消息(Webhook 暂停或关闭时)和已过滤的消息(聊天 Webhook 的竞争报价选项)。
  • 80 %。 本月消息达到 400 条时,所有者会收到一封邮件。
  • 积分用完。 本月 500 条用完且积分耗尽时,组织的 Webhook 会暂停(已暂停(积分不足)),所有者会收到一封邮件。充值后或下个月开始时,它们会自动恢复。余额归零后,大约还会有一分钟的消息送达;余额不会变成负数。
  • 在哪里查看: Webhook 推送页面顶部显示本月消息数、500 条中剩余的数量和本月 Webhook 花费的积分;账单与积分 的积分卡片显示同样的内容;积分明细中每次扣费一行;推送记录显示每次推送的计费消息数。

推送记录

设置 → Webhook 推送 → 推送记录 列出最近 30 天的每次推送和每条消息,最新的在前。可以从 Webhook 推送页面顶部的按钮打开,也可以从某个 Webhook 所在行打开(查看它的推送记录,已按该 Webhook 筛选),或点击聊天卡片上的“+N more”链接。

查看 在两个列表之间切换:

列表每行是列
推送批次一个 HTTPS 请求或一张聊天卡片发送时间、Webhook(名称和推送方式)、结果(测试推送带 测试 标签)、发送消息数、计费消息数(扣费后显示“已计费”)、HTTP 状态码、尝试次数、错误信息
消息一条亚马逊消息接收时间、通知类型、所属店铺(不涉及你的店铺时显示“不是 SellerSheet 中的店铺”)、SKU / ASIN、推送结果(它在每个 Webhook 的结果,或“没有 Webhook 接收”)

筛选条件保存在页面地址中,筛选后的视图可以收藏或分享:

  • 两个列表都有 Webhook 和 时间范围(最近 1 小时、最近 24 小时、最近 7 天、最近 30 天)。
  • 结果:推送批次为 已送达 或 发送失败;消息另有 未发送 和 已过滤。
  • 仅消息列表:通知类型、所属店铺,以及 搜索 SKU 或 ASIN——完整的 SKU,或 ASIN。
  • 重置 清除筛选。列 按钮用来显示或隐藏列。
结果含义
已送达目标接受了它。超出本月免费 500 条后计费。
发送失败每次尝试都失败,或这个 Webhook 积压太多。不计费,也不会再发送。
未发送消息到达时 Webhook 处于暂停或关闭状态。不计费,之后也不补发。
已过滤聊天 Webhook 开启了 竞争报价:仅在卖家或购物车赢家变化时推送,而这条消息只有价格变化。不计费。

在某条消息上点 查看详情,会显示它的 消息 ID、接收时间、事件时间、所属店铺、SKU / ASIN、消息指纹、它在每个 Webhook 的结果,以及 推送的消息内容——与送达时完全一致的消息 JSON,可点 复制 JSON。JSON 在消息到达几分钟后才可查看(在此之前面板会提示稍后再打开),保留 30 天。

常见问题排查

发送测试、推送记录的 错误信息 列和暂停横幅会显示目标自己的回复:

你看到的处理
Feishu 19021签名校验失败:按飞书显示的原样重新粘贴密钥——如果机器人没有开启签名校验,就删除密钥。
Feishu 19022机器人设置了 IP 白名单:联系客服获取需放行的 IP。
Feishu 19024关键词校验失败:添加关键词 SellerSheet。
DingTalk 310000安全设置拒收:检查关键词 SellerSheet、加签密钥或 IP 设置。
DingTalk 300001 · WeCom 93000机器人地址已失效:重新复制地址。
DingTalk 130101 · WeCom 45009触发了应用的频率限制:多个 Webhook 推送到同一个群。把它们合并成一个。
Slack: invalid_token, no_serviceSlack webhook 已被删除:新建一个。
Teams: …工作流拒收:在 Teams 中检查该工作流。
HTTP 3xx (redirects are not followed)使用最终地址。
接收端返回 HTTP 401 / 403你的签名校验拒绝了请求:基于原始请求体、用 Webhook 上保存的密钥校验。
no answer within 10 s先返回 2xx,之后再处理。
could not connect接收端已停止,或无法从公网访问。
That address is not on the public internet使用公网 https:// 地址,端口 443。

Webhook 收不到任何消息:

  • 它的状态是 推送中——没有暂停或关闭。
  • 在拥有该店铺的工作区里,勾选了你要的通知和店铺。
  • 如果变化发生在你没有连接的站点,包括未连接到 SellerSheet 的站点 需要打开。
  • 在推送记录的 消息 列表里,可以看到消息是否到达,以及它在每个 Webhook 的结果(未发送、已过滤、“没有 Webhook 接收”)。
  • 编辑面板中店铺单元格上的标记会说明亚马逊拒绝了订阅。若标记指出店铺授权缺少某项权限,请在店铺与市场重新授权该店铺;仍然失败请联系客服。

常见问题

谁可以管理 Webhook?

工作区的所有者或管理员。成员看不到 Webhook 推送页面。

一个工作区可以有几个 Webhook?

最多 10 个。

为什么有些通知不能勾选?

灰色的行是这个 Webhook 无法接收的通知:亚马逊广告(以数据形式进入你的报表,不作为 Webhook 推送)或物流追踪节点(暂未开放),或推送到聊天群时仅限 HTTPS 的——每小时指标、每次变动一条消息,或供你自己的程序使用。行上会注明原因。

Webhook 怎么收费?

每个组织每月免费送达 500 条消息,所有套餐都一样。超出部分每条送达的消息从组织的积分中扣费,价格显示在 Webhook 推送页面上。测试、发送失败、未发送和已过滤的消息从不计费。

Webhook 能发邮件吗?

不能。邮件不是推送目标,请使用聊天群或 HTTPS 接收端点。SellerSheet 仍会用邮件发送自己的通知:Webhook 因连续推送失败而暂停时发给所有者和管理员;本月免费消息用到 80 % 和积分用完时发给所有者。

Webhook 会读取我的 Google 表格吗?

不会。Webhook 只转发亚马逊的通知;SellerSheet 推送时不读写你的表格。

SellerSheet 店铺提醒去哪了?

店铺提醒现在就是 Webhook 推送。同样的通知和聊天应用,另有 17 类亚马逊通知,所有套餐可用,每个工作区最多 10 个,还能用 HTTPS 推送到你自己的系统。

本页内容

操作

查看 Markdown

询问助手

问 ChatGPT问 Claude