消息推送

订阅 Shopee Open Platform 的Webhook可以帮助您在特定事件发生时立即获得通知。 这使您可以及时接收事件的更新，而无需定期轮询 API 端点。请注意，Push Mechanism只是通知您对应数据已更改，若想获取更多信息，请调用对应的接口获取最新数据。建议您将Push Mechanism（Webhook）和API配合使用，使您的系统集成更加高效。

下面概述了 Webhook 在 Shopee 开放平台上的工作方式：

• 您为您的应用订阅特定的 webhook 类型并定义回调URL。
• 发生特定事件，例如订单状态更新。
• Shopee 向回调URL发送HTTP POST请求。
• 您通过回调URL收到通知。

Shopee 开放平台上有 5 类 webhooks 可用：

• Shopee - 用于商店授权和重要 Shopee 更新的 Webhook。
• Order （订单）- 用于订单状态和跟踪号更新的 Webhook。
• Marketing（营销） - 用于跟踪产品促销活动的 Webhook。
• Product（商品） - 用于商品信息、违规和品牌注册流程更新的 Webhook。
• Chat（聊天） - 用于买家聊天信息更新的 Webhook。

Shopee Push

• Shop Authorization Push (Code:1) ：店铺授权成功通知

当卖家操作您的系统进行授权操作时，您将立即收到通知。特别是用主账号授权时，回调地址只返回main account id, 当您订阅此通知，可以及时获取到卖家当次授权成功的shop id列表和merchant id列表。

• Shop Authorization Canceled Push (Code:2) ：店铺解除授权成功通知

卖家可以通过卖家中心或者您的系统进行授权操作时，您将会立即收到通知。特别是用主账号解除授权时，回调地址只返回main account id, 当您订阅此通知，可以及时获取到卖家当次解除授权成功的shop id列表和merchant id列表。

• OpenAPI Authorization Expiry Push (Code:12)：店铺授权过期通知

卖家授权有效期为一年，授权到期前，卖家需要手动再完成店铺授权，当您订阅此通知后，我们将会推送即将在7天后过期的shop id和merchant id列表，您可以联系卖家进行再次授权，避免因为授权过期而无法正常调用接口。

• Shopee Updates (Code:5)：Shopee官方消息通知

当您订阅此通知，您能及时获取Shopee官方消息通知。

Product Push

• Reserved Stock Change Push (Code:8)：商品活动库存变更通知

商品参与活动后，当您订阅此通知，即可获取每次活动库存被消耗的记录，便于卖家及时监控活动库存变化。

• Video Upload Push (Code:11)：视频转码成功通知

如果卖家需要为商品上传视频介绍，只有成功转码的视频文件才能调用添加或更新商品的接口，您可以订阅此通知，当调用完v2.media_space.complete_video_upload接口后，等待此消息通知，通知将会返回转码成功还是失败，返回转码成功后，您再继续将video_upload_id添加或更新商品接口。

• Banned Item Push (Code:6)：商品禁用通知

商品被Shopee审核后标记为禁用，您可以订阅此通知，您可以即使了解到被Shopee禁用的商品，以及了解被禁用的原因，快速修正商品信息，恢复上架。

• Brand Register Result Push (Code:13)：品牌审核结果通知

卖家可以通过v2.product.register_brand接口或者卖家中心注册卖家自有品牌，从而可以再添加商品时填写卖家自有品牌。但注册后需要通过Shopee人员审核，审核通过后的品牌ID可正式用于商品，当您订阅此通知，您可以及时获取到三种审核结果，审核通过/审核拒绝/现有品牌合并。

Order Push

• Order Status Update Push (Code:3)：订单状态变更通知

当订单状态发生变更时(包含所有订单状态)，您将会立即收到通知。特别是未发货前订单被取消,您可以及时收到通知。

• Order TrackingNo Push (Code:4)：订单物流跟踪号通知

渠道返回物流跟踪号一般有延时，而部分渠道要求打印面单前需生成跟踪号，当您订阅此通知，物流跟踪号返回时，您可以立即收到通知，帮助您快速出货，减少轮询v2.logistics.get_tracking_number接口的次数。

• Shipping_document_status_push(Code:15)：订单面单生成状态通知

当订单的面单生成状态有更新时，例如ready或者failed，您都会收到通知，订阅此通知，可以避免您多次调用v2.logistics.get_shipping_document_result 接口来获取面单生成结果。

Marketing Push

• Item Promotion Push (Code:7)：商品参与/退出活动通知

当您订阅此通知，可以及时获取到商品开始显示活动库存，以及因为活动结束或者商品移出活动而不再显示活动库存的通知。

• Promotion Update Push (Code:9)：活动变更通知

当您订阅此通知，您可以及时获取到活动被创建，参与活动的产品列表更新，活动结束的通知。

Chat Push

• Webchat Push (Code:10)：聊聊信息通知

当您订阅此通知，买家发送消息时，您能及时获取买家发送的信息。

第一步：您需要登录控制台，选择您需要订阅的App，点击设置

第二步：设置回调地址并验证

*点击验证后，Shopee会发送Post请求到您的回调地址，以验证您的回调地址可用。当验证失败时，您可以查看到具体的错误原因。

第三步：打开您需要订阅的信息类型开关

您可以通过v2.push.set_push_config接口设置开关，也可以通过控制台打开

您也选择需要关闭的订阅服务，通过接口和控制台进行设置关闭。

*请注意不同类型的app类型能打开的推送类型不一样

第四步（可选）：如果您的系统需要添加外IP白名单才可以访问，请通过v2.public.get_shopee_ip_ranges接口获取API的出口地址，如果您在测试推送服务，可以调用沙箱环境的v2.public.get_shopee_ip_ranges接口获取API出口地址，如果您已经使用生产环境，请调用生产环境的v2.public.get_shopee_ip_ranges接口

为了防止他人攻击，我们在每个请求中都提供了授权签名，位于 HTTP 请求头的 Authorization 字段中，您可以识别Shopee的签名后消费信息。从技术上讲，该步骤是可选的，但我们强烈建议开发人员使用以下步骤来验证请求，以生成签名并确保它与推送的匹配。下面是我们生成签名的方法

1.将 URL、|、response.content作为签名基本字符串。 例如：

‘http://www.example.com/example/uri|{“shop_id”: 123, “code”: 1, “success”: 1, “extra”: “shop_id 123 is authorized successfully”, “data”: {“more_info”: “more info”}, “timestamp”: 1470198856}’

注意不建议采用json.loads(response.content)方法

2.拿到您的partner key

3.最后，通过将签名基础字符串和partner key传递给 HMAC-SHA256 散列算法来计算签名。 HMAC 签名函数的输出是一个二进制字符串。 这需要进行十六进制编码以生成签名字符串。

Code demo

Python：

import hmac

def verify_push_msg(url, request_body, partner_key, authorization):

    base_string = url + '|' + request_body

    cal_auth = hmac.new(partner_key, base_string, hashlib.sha256).hexdigest()

    if cal_auth != authorization:

        return False

    else:

        return True

Go:

package verify

import (

    "crypto/hmac"

    "crypto/sha256"

    "encoding/hex"

    "fmt"

)

 

 

func VerifyPushMsg(url, requestBody, partnerKey, authorization string) (result bool) {

    baseStr := url + "|" + requestBody

    h := hmac.New(sha256.New, []byte(partnerKey))

    h.Write([]byte(baseStr))

    calAuth := fmt.Sprintf("%x", h.Sum(nil))

    if authorization != calAuth {

        return false

    }

    return true

}

Java:

import javax.crypto.Mac;

import javax.crypto.spec.SecretKeySpec;

import org.apache.commons.codec.binary.Hex;

import java.io.UnsupportedEncodingException;

import java.security.NoSuchAlgorithmException;

 

 

public static Boolean verfiyPushMsg(String url, String requestBody, String partnerKey, String authorization)

        throws NoSuchAlgorithmException, UnsupportedEncodingException, java.security.InvalidKeyException {

 

    String baseStr = url + "|" + requestBody;

    Mac sha256_HMAC = Mac.getInstance("HmacSHA256");

    SecretKeySpec secret_key = new SecretKeySpec(partnerKey.getBytes("UTF-8"), "HmacSHA256");

    sha256_HMAC.init(secret_key);

    String result = Hex.encodeHexString(sha256_HMAC.doFinal(baseStr.getBytes("UTF-8")));

    return result.equals(authorization);

}

请保证您设置的partner id已经有授权成功的店铺，如果没有，请先完成店铺授权。如果已经完成，请选择已经授权成功的店铺操作各种事件。详细可以查看各Push API文档了解各种事件触发条件，您的回调地址应在收到我们的请求后提供成功的响应。

您可以通过v2.push.set_push_config接口blocked_shop_id字段设置（最多只能设置500个shop)，也可以通过控制台设置

为了避免重复推送，您的回调地址应在收到我们的请求后提供适当的响应。 我们需要一个状态码为 2xx 且正文为空的 HTTP 响应。每个Push类型最多支持推送的次数和间隔多久重推，可以查看具体的Push文档。

避免推送失败的请求一直占用推送消息资源，我们有一定的推送关停告警和关停推送服务的操作。为此，我们会统计过去6小时推送成功的成功率。如果在超时时间内（每个Push类型的超时时间可以通过Push文档查看）我们没有接收到您返回状态码为 2xx 且正文为空的 HTTP 响应，我们将会记录一次失败。

当前平台推送告警策略：如果在过去6小时内推送消息超过600条且推送成功率低于70%，系统会保持每30分钟自动向开发者发送警告邮件。 直到成功率恢复到 70% 以上才会关闭警报。

当前平台推送关停策略：如果某开发者在过去6小时内推送消息超过600条且推送成功率低于30%，平台将自动关闭该开发者的推送服务，并通过电子邮件通知。

您可以通过控制台查看到当前Push的状态和成功率。

当推送被平台关停后，您可以先检查您的消息接收服务问题，确保能正常接收消息后再重新订阅即可。关停期间的Push消息不再推送，重新开启Push服务，成功率将重新计算。