Webhook 配置指南

Webhook 配置指南

配置 Webhook，当你的 atoship 账户中发生物流事件时即可实时收到通知。

什么是 Webhook？

定义： Webhook 是当特定事件发生时，由 atoship 自动向你的服务器发送的消息。

优势：

• 实时通知
• 自动化工作流
• 减少轮询
• 即时更新

支持的事件

物流事件：

订单事件：

创建 Webhook

操作步骤：

1. 进入 设置 → Webhook
2. 点击“添加 Webhook”
3. 输入接收端点 URL
4. 选择要订阅的事件
5. 保存配置

端点要求

你的服务器必须满足：

• 接受 POST 请求
• 使用 HTTPS（必需）
• 在 30 秒内响应
• 返回 2xx 状态码

Webhook 载荷

载荷示例：

{
  "event": "label.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "label_id": "lbl_abc123",
    "tracking_number": "9400111899223",
    "carrier": "USPS",
    "service": "Priority Mail",
    "order_id": "ord_xyz789"
  }
}

验证 Webhook

签名验证：

X-AtoShip-Signature: sha256=abc123...

在代码中验证：

const crypto = require('crypto');
const signature = req.headers['x-atoship-signature'];
const expected = 'sha256=' +
  crypto.createHmac('sha256', secret)
    .update(JSON.stringify(req.body))
    .digest('hex');
const valid = signature === expected;

重试策略

投递失败时：

• 最多重试 5 次
• 采用指数退避
• 1min → 5min → 30min → 2hr → 24hr

测试 Webhook

测试方法：

1. 使用 Webhook 测试工具
2. 从后台发送测试事件
3. 查看 Webhook 日志
4. 确认已收到载荷

常见使用场景

自动化示例：

• 更新订单管理系统
• 发送自定义通知
• 触发库存更新
• 记录物流数据
• 异常时发出告警

物流轨迹更新

轨迹事件流程：

Accepted → In Transit →
Out for Delivery → Delivered

异常事件：

• 尝试派送
• 地址问题
• 包裹被暂扣
• 退回寄件人

多端点配置

高级配置：

• 不同事件对应不同 URL
• 按环境区分端点
• 备用端点

错误处理

最佳实践：

1. 记录所有收到的 Webhook
2. 异步处理
3. 立即返回 200
4. 处理重复事件
5. 验证签名

Webhook 日志

查看历史记录：

• 所有已发送的 Webhook
• 响应状态码
• 重试次数
• 载荷详情

安全注意事项

保护你的端点：

• 始终验证签名
• 仅使用 HTTPS
• 将 atoship 的 IP 加入白名单
• 不要泄露密钥

IP 白名单

atoship IP：

52.xx.xx.xx
54.xx.xx.xx
(Check dashboard for current list)

故障排查

收不到 Webhook：

1. 核对端点 URL
2. 检查 HTTPS 证书
3. 确认防火墙规则
4. 测试端点是否可访问
5. 查看 Webhook 日志

事件重复：

• 实现幂等处理
• 跟踪事件 ID
• 跳过已处理的事件

停用 Webhook

暂停或删除：

1. 设置 → Webhook
2. 选择目标 Webhook
3. 关闭开关或删除
4. 确认操作

速率限制

投递上限：

• 每分钟最多 1000 个事件
• 每个端点独立限制
• 突发流量处理