API Reference

Webhook API 文档 V1.2

Webhook API 文档

通过 Webhook 订阅，您可以接收 Mamba 系统中特定事件的实时通知推送。例如：批量导入完成、表单用户订阅等。

📋 基础信息

什么是 Webhook？

Webhook 是一种服务器间的事件通知机制。当 Mamba 系统中发生特定事件时，会主动向您配置的 URL 发送 HTTP POST 请求，将事件数据推送给您。

核心能力

  • 批量导入任务完成通知
  • 表单收集用户订阅数据推送
  • 客户营销状态变更推送

支持的 Topics

Topic说明
bulk_operations/finish批量导入处理完成推送
customer/newsletter通过 Mamba 表单收集用户
customer/marketing客户营销订阅状态变更

🔑 认证方式

API 服务地址

  • 生产环境： https://api.mambasms.com

请求头

Content-Type: application/json
X-Mamba-Access-Token: shop_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Token 获取方式：登录 Mamba 后台 → 店铺设置 → 连接新店铺 → API CONNECT → 查看 API 密钥

📡 接口列表

方法路径说明
POST/api/v1/webhooks创建 Webhook
PUT/api/v1/webhooks更新 Webhook
GET/api/v1/webhooks查询 Webhook 列表
GET/api/v1/webhooks/count查询 Webhook 数量
DELETE/api/v1/webhooks/{webHookId}删除 Webhook

📝 1. 创建 Webhook

POST /api/v1/webhooks

创建一个新的 Webhook 订阅。同一个 topic 只能创建一个 webhook，重复创建会更新已有配置。

请求参数

字段类型必填说明
topicString✅订阅的事件类型，见支持的 Topics 列表
urlString✅接收推送的 URL 地址（最大 500 字符）

请求示例

{
  "topic": "customer/newsletter",
  "url": "https://your-domain.com/api/webhook/receive"
}

响应示例

成功（200）：

{
  "code": 200,
  "data": {
    "topic": "customer/newsletter",
    "url": "https://your-domain.com/api/webhook/receive",
    "format": "json",
    "createdAt": 1680170229
  }
}

失败（400）：

{
  "code": 400,
  "message": "Topic noneffective"
}

📝 2. 更新 Webhook

PUT /api/v1/webhooks

更新已有的 Webhook 配置（按 topic 匹配更新）。

请求参数

字段类型必填说明
topicString✅订阅的事件类型
urlString✅新的接收推送 URL 地址（最大 500 字符）

请求示例

{
  "topic": "customer/newsletter",
  "url": "https://your-domain.com/api/webhook/new-endpoint"
}

响应示例

成功（200）：

{
  "code": 200,
  "data": {
    "topic": "customer/newsletter",
    "url": "https://your-domain.com/api/webhook/new-endpoint",
    "format": "json",
    "createdAt": 1680170229
  }
}

📝 3. 查询 Webhook 列表

GET /api/v1/webhooks

查询当前店铺已配置的所有 Webhook。

请求参数

无

响应示例

成功（200）：

{
  "code": 200,
  "data": {
    "list": [
      {
        "id": "6319202871720443931",
        "topic": "bulk_operations/finish",
        "url": "https://your-domain.com/api/webhook/bulk",
        "format": "json",
        "createdAt": 1680170229
      },
      {
        "id": "6319202871720443932",
        "topic": "customer/newsletter",
        "url": "https://your-domain.com/api/webhook/customer",
        "format": "json",
        "createdAt": 1680170300
      }
    ],
    "total": 2
  }
}

📝 4. 查询 Webhook 数量

GET /api/v1/webhooks/count

返回当前店铺已配置的 Webhook 总数。

请求参数

无

响应示例

成功（200）：

{
  "code": 200,
  "data": 2
}

📝 5. 删除 Webhook

DELETE /api/v1/webhooks/{webHookId}

删除指定的 Webhook 订阅。

路径参数

字段类型必填说明
webHookIdString✅Webhook ID（从查询列表接口获取）

响应示例

成功（200）：

{
  "code": 200,
  "data": true
}

🔔 Webhook 推送说明

当事件触发时，Mamba 会向您配置的 URL 发送 HTTP POST 请求。

推送请求头

Header说明
Content-Typeapplication/json
X-Mamba-hmac-sha256HMAC-SHA256 签名（用于验证请求来源）
X-Mamba-Topic事件类型（如 customer/newsletter）
X-Mamba-Webhook-IdWebhook 记录 ID

签名验证

Mamba 使用您的 API 密钥（security_key）对请求体进行 HMAC-SHA256 签名，签名结果以 Base64 编码放在 X-Mamba-hmac-sha256 请求头中。

验证步骤：

  1. 获取请求体原始内容（raw body）
  2. 使用您的 API 密钥作为 secret，对请求体计算 HMAC-SHA256
  3. 将结果进行 Base64 编码
  4. 与 X-Mamba-hmac-sha256 请求头的值进行比较

验证示例（Java）：

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.apache.commons.codec.binary.Base64;

public static String calculateHmac(String message, String secret) {
    Mac hmac = Mac.getInstance("HmacSHA256");
    SecretKeySpec key = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
    hmac.init(key);
    return Base64.encodeBase64String(hmac.doFinal(message.getBytes()));
}

// 验证
String expectedSignature = calculateHmac(requestBody, yourSecretKey);
boolean isValid = expectedSignature.equals(request.getHeader("X-Mamba-hmac-sha256"));

验证示例（Node.js）：

const crypto = require('crypto');

function verifyWebhook(body, secret, signature) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(body);
  const calculated = hmac.digest('base64');
  return calculated === signature;
}

验证示例（Python）：

import hmac
import hashlib
import base64

def verify_webhook(body: str, secret: str, signature: str) -> bool:
    calculated = base64.b64encode(
        hmac.new(secret.encode(), body.encode(), hashlib.sha256).digest()
    ).decode()
    return calculated == signature

推送响应要求

  • 您的接口需要返回 HTTP 200 状态码表示接收成功
  • 非 200 状态码会触发重试机制

重试机制

  • 最大重试次数：5 次
  • 初始延迟：5 秒
  • 退避策略：指数退避（multiplier = 2.0）
  • 重试间隔：5s → 10s → 20s → 40s → 80s

📦 推送数据格式

bulk_operations/finish

批量导入任务处理完成时推送。

{
  "endpoint": "products",
  "status": "SUCCESS"
}
字段类型说明
endpointString批量导入的数据类型：customers、orders、products
statusString处理结果：SUCCESS 或 FAIL

customer/newsletter

通过 Mamba 表单收集到新的订阅用户时推送。

{
  "id": "32296",
  "email": "[email protected]",
  "phone": "+1234567890",
  "first_name": "John",
  "last_name": "Doe",
  "city": "New York",
  "gender": "",
  "birthdate": "",
  "country_code": "US",
  "created_at": 1680170229,
  "source": "customer/newsletter",
  "email_marketing_consent": {
    "state": "subscribed",
    "updated_at": 1680170229
  },
  "sms_marketing_consent": {
    "state": "undefined"
  }
}
字段类型说明
idString独立站顾客 ID（非 Mamba 系统 ID）。新用户留空
emailString邮箱地址
phoneString手机号
first_nameString名
last_nameString姓
cityString城市
genderString性别
birthdateString生日
country_codeString国家代码
created_atLong创建时间（Unix 时间戳，秒）
sourceString固定值：customer/newsletter
email_marketing_consent.stateString邮件订阅状态：subscribed / undefined
sms_marketing_consent.stateString短信订阅状态：subscribed / undefined

customer/marketing

客户营销订阅状态变更时推送（如邮件/短信订阅状态从未订阅变为已订阅，或从已订阅变为退订）。

⚠️

注意： 推送格式根据店铺类型不同有所差异，请根据下方的示例适配。

格式一：API 直连店铺（sys_api）

{
  "id": "32296",
  "email": "[email protected]",
  "phone": "+1234567890",
  "first_name": "John",
  "last_name": "Doe",
  "city": "New York",
  "gender": "",
  "birthdate": "",
  "country_code": "US",
  "created_at": 1680170229,
  "email_marketing_consent": {
    "state": "SUBSCRIBED",
    "updated_at": 1680170229
  },
  "sms_marketing_consent": {
    "state": "UNSUBSCRIBED",
    "updated_at": 1680170229
  }
}
字段类型说明
idString独立站顾客 ID
emailString邮箱地址
phoneString手机号
email_marketing_consent.stateString邮件订阅状态：SUBSCRIBED / UNSUBSCRIBED / NOT_SUBSCRIBED
sms_marketing_consent.stateString短信订阅状态：SUBSCRIBED / UNSUBSCRIBED / NOT_SUBSCRIBED

格式二：平台店铺（Shopify / Shopline / Shoplazza 等）

{
  "audienceId": "417206294256552580",
  "originId": "50009305",
  "shopId": "397182478115689307",
  "email": "[email protected]",
  "phone": "",
  "firstName": "",
  "lastName": "",
  "city": "",
  "gender": "",
  "birthDate": "",
  "countryCode": "",
  "createdAt": 1780906915,
  "updatedAt": 1780907000,
  "emailMarketingConsent": {
    "state": 2,
    "updatedAt": 1780907000
  },
  "smsMarketingConsent": {
    "state": 0,
    "updatedAt": 0
  }
}
字段类型说明
audienceIdStringMamba 系统内部受众 ID
originIdString平台端顾客 ID（如 Shopify Customer ID）
shopIdStringMamba 系统店铺 ID
emailString邮箱地址
phoneString手机号
firstNameString名
lastNameString姓
cityString城市
genderString性别
birthDateString生日
countryCodeString国家代码
createdAtLong客户创建时间（Unix 时间戳，秒）
updatedAtLong状态更新时间（Unix 时间戳，秒）
emailMarketingConsent.stateInteger邮件订阅状态：1=已订阅 / 2=已退订 / 0=未订阅
emailMarketingConsent.updatedAtLong邮件订阅状态更新时间（Unix 时间戳，秒）
smsMarketingConsent.stateInteger短信订阅状态：1=已订阅 / 2=已退订 / 0=未订阅
smsMarketingConsent.updatedAtLong短信订阅状态更新时间（Unix 时间戳，秒）

⚠️ 重要注意事项

1. Topic 唯一性

每个店铺的每个 topic 只能配置一个 webhook URL。重复创建同一 topic 会覆盖之前的配置。

2. URL 要求

  • 必须是可公网访问的 HTTPS 地址
  • 最大长度 500 字符
  • 需要能正常响应 POST 请求并返回 200 状态码

3. 安全建议

  • 务必验证签名：通过 X-Mamba-hmac-sha256 验证请求确实来自 Mamba
  • IP 白名单：如果您的服务有 IP 限制，请将 Mamba 服务器 IP 47.252.51.206 加入白名单
  • Cloudflare 用户：如果使用 Cloudflare，请对 webhook 接收路径关闭 Bot Fight Mode，避免请求被拦截

4. 错误码说明

HTTP 状态码说明
200成功
400参数错误（如 topic 无效、url 为空）
401Token 无效或未提供
429请求过于频繁

🚀 快速开始

1. 获取 API Token

登录 Mamba 后台 → 店铺设置 → 连接新店铺 → API CONNECT → 查看 API 密钥

2. 创建 Webhook 订阅

curl -X POST "https://api.mambasms.com/api/v1/webhooks" \
  -H "Content-Type: application/json" \
  -H "X-Mamba-Access-Token: shop_your_token_here" \
  -d '{
    "topic": "customer/newsletter",
    "url": "https://your-domain.com/api/webhook/receive"
  }'

3. 开发接收接口

您的接收接口需要：

  1. 接受 POST 请求
  2. 解析 JSON 请求体
  3. 验证 X-Mamba-hmac-sha256 签名
  4. 处理业务逻辑
  5. 返回 HTTP 200

4. 验证 Webhook 配置

# 查询已配置的 webhook
curl -X GET "https://api.mambasms.com/api/v1/webhooks" \
  -H "X-Mamba-Access-Token: shop_your_token_here"

📚 属性介绍

Customer Properties 详细说明请参考：Customer Properties

Updated 14 days ago

Updated 14 days ago