---
title: "概述"
doc_type: static
doc_category: static
doc_version: v20270301
source_url:
html: 'https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/webhooks/overview'
md: 'https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/webhooks/overview.md'
---
# 概述
Webhook 是一种事件驱动的消息推送机制，可用于保持应用与 SHOPLINE 店铺之间的数据同步，或在店铺发生特定事件后触发相应处理操作的执行。相比于持续轮询，Webhook 提供了一种更高效、低延迟的方法来获取店铺数据的更改信息。
当店铺发生特定事件时（如商品更新），SHOPLINE 会立即向你的应用服务器发送 HTTP 请求。你的服务器收到请求后可及时更新数据，从而确保应用数据与 SHOPLINE 一致。
------
## 准备工作
为确保你的应用能收到 Webhook 通知，需满足以下条件：
- 目标店铺已安装了你的应用。
- 你的应用已订阅了对应 API 版本的目标事件。
------
## 应用订阅事件
按照以下步骤完成事件订阅：
1. 前往 [合作伙伴后台](https://admin.myshopline.com/user/signIn?sl_state=scene%3Ddeveloper%26redirect_url%3Dhttps%3A%2F%2Fdeveloper.myshopline.com%2Fapp%2Flist) 申请开发者账号。
2. [创建一个应用](https://developer.shopline.com/zh-hans-cn/docs/apps/application-management/creating-an-app.md)。
3. 调用 [订阅 Webhook](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/webhook/subscribe-to-a-webhook.md) 接口订阅目标事件。
------
## Webhook 推送请求格式
当 SHOPLINE 店铺内发生你已订阅的事件时（如订单、商品等实体的变更），SHOPLINE 会主动以 HTTP POST 请求的方式将消息发送到你为事件配置的接收端点上。
### 请求头
| **参数** | **类型** | **必填** | **描述** |
| ---------------------- | -------- | -------- | ------------------------------------------------------------ |
| X-Shopline-Topic | string | 是 | 事件的唯一标识。
例子：`orders/update` |
| X-Shopline-Hmac-Sha256 | string | 是 | 该请求的签名。收到请求后，你需要对该签名进行 [验签](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/generate-and-verify-signatures.md#post-请求操作步骤) 以验证数据的真实性和完整性。 |
| X-Shopline-Shop-Domain | string | 是 | 店铺域名。 |
| X-Shopline-Shop-Id | string | 是 | 店铺 ID。 |
| X-Shopline-Merchant-Id | string | 是 | 商家 ID。 |
| X-Shopline-API-Version | string | 是 | API 版本号。
例子：`v20260901` |
| X-Shopline-Webhook-Id | string | 是 | 该 Webhook 事件的 ID。当触发重试机制时，该 ID 保持不变。 |
示例：
```plain
{
"X-Shopline-Topic":"orders/edited",//事件的唯一标识。
"X-Shopline-Hmac-Sha256":"XWmrwMey6OsLMeiZKwP4FppHH3cmAiiJJAweH5Jo4bM=",//该请求的签名。
"X-Shopline-Shop-Domain":"yourhandle.myshopline.com",//店铺的域名。
"X-Shopline-Shop-Id":"*******123456",//店铺 ID。
"X-Shopline-Merchant-Id":"*******234",//商家 ID。
"X-Shopline-API-Version":"v20260901",//API 版本号。
"X-Shopline-Webhook-Id":"b54557e48a5fbf7d70bcd043" //该 Webhook 事件的 ID。
}
```
### 请求体
请求体内容以事件定义为准，以下以 [客户新增](https://developer.shopline.com/zh-hans-cn/docs/webhook/customers/customer-add.md) 事件为例展示请求体的数据格式。
> **注意**
>
> 你在合作伙伴后台订阅事件时选择的 API 版本号决定了系统推送的事件定义。你的应用对 Webhook 事件的解析和处理逻辑，必须与该版本对应的事件定义保持一致。
示例：
```plain
{
"total_spent":"0",
"addresses":[
{
"zip":"",
"country":"",
"address2":"",
"city":"",
"address1":"",
"last_name":"",
"province_code":"",
"country_code":"",
"default":true,
"province":"",
"phone":"",
"company":"",
"id":"SL201UA592875161232815849",
"customer_id":"******390",
"first_name":""
}
],
"gender":"others",
"last_order_id":"1001",
"created_at":"2023-05-10T17:00:01+08:00",
"language":"en",
"verified_email":false,
"accepts_mobile_marketing":false,
"accepts_marketing_updated_at":"2023-05-10T17:00:01+08:00",
"orders_count":1,
"default_address":{
"zip":"",
"country":"",
"address2":"",
"city":"",
"address1":"",
"last_name":"",
"province_code":"",
"country_code":"",
"default":true,
"province":"",
"phone":"",
"company":"",
"id":"SL201UA592875161228158749",
"customer_id":"******390",
"first_name":""
},
"updated_at":"2023-05-26T19:25:47+08:00",
"accepts_marketing":true,
"email_subscribe_flag":1,
"nick_name":"test1",
"currency":"CLP",
"id":"******390",
"state":3,
"first_name":"test1",
"email":"****@example.com",
"mobile_subscribe_flag":2
}
```
------
## 事件推送和重试规约
为了保证事件通知的实时性，SHOPLINE 建立了标准的推送机制与失败重试策略。
### 推送与响应机制
SHOPLINE 通过 HTTP POST 方式推送事件，请求头 `Content-Type` 为 `application/json`，事件数据以 JSON 格式置于请求体中。系统发出事件推送后，你的应用必须在 5 秒内按照示例格式进行应答，以告知 SHOPLINE 事件推送成功。否则，SHOPLINE 将判定推送失败并触发重试。
成功应答示例：
```plain
HTTP/1.1 200 OK
```
### 重试策略
当事件推送被判定为失败时，SHOPLINE 会启动自动重试机制。系统会在推送失败后的 48 小时内完成最多 19 次重试。每次重试与上一次之间的时间间隔呈阶梯式增长：0 秒、5 秒、10 秒、30 秒、45 秒、1 分钟、2 分钟、5 分钟、12 分钟、38 分钟、1 小时、2 小时、4 小时、4 小时、4 小时、4 小时、4 小时、4 小时、4 小时。
如果一条事件推送连续 19 次重试失败，且在重试阶段内没有其他同类型事件推送成功的记录，SHOPLINE 将移除你的应用针对该事件的订阅记录，并向你发送一封标题为“Webhook 事件订阅删除”的邮件。
> **注意**
>
> SHOPLINE 可能重复推送同一事件。你的应用必须具备处理重复通知的能力。若你的应用收到重复的事件推送，且该事件已被成功处理，直接返回 HTTP `200 OK` 即可。
------
## 注意事项
使用 Webhook 时，注意如下事项：
- Webhook 事件推送无法保证 100% 的送达率。为保障业务数据的最终一致性，强烈建议你的应用接入相关查询接口。例如，你的应用在订阅 [订单创建](https://developer.shopline.com/zh-hans-cn/docs/webhook/order/order-created.md) 事件的同时，可调用 [查询订单](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/order/order-management/get-orders.md) 接口主动核对订单状态。
- 一旦事件订阅被删除，SHOPLINE 将立即停止该事件的任何消息推送。如需恢复接收，必须重新创建该事件订阅。
------
## 签名验证
为确保 Webhook 推送消息的真实性和安全性，建议你的应用在收到事件推送时进行签名验证。关于更多验签相关信息，参考 [加签和验签](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/generate-and-verify-signatures.md)。
- **签名算法**：HMAC-SHA256
- **验签内容**：原始 [请求体](#请求体) 字符串
- **签名密钥**：应用的 APP Secret