Webhooks
当你的 Atoship 账户发生事件时，实时接收通知。 借助 Webhooks，你可以构建自动响应物流事件的集成方案。
什么是 Webhooks？
Webhooks 是一种 HTTP 回调机制，当你的 Atoship 账户发生事件时，会主动通知你的应用。 无需反复轮询我们的 API 获取更新，Webhooks 会把数据实时推送到你的服务器。
实时更新
事件发生时立即收到通知
减少 API 调用
无需轮询即可获取更新
自动化工作流
根据物流事件自动触发操作
快速上手
1. 创建 Webhook 端点
curl -X POST https://atoship.com/api/v1/webhooks \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Order Notifications",
"url": "https://example.com/webhooks/atoship",
"event_types": ["label.purchased", "tracking.delivered"],
"retry_attempts": 3,
"timeout": 30
}'2. 响应
响应中会返回一个 webhook 密钥。请妥善保存 —— 验证 webhook 签名时需要用到它。
{
"id": "whk_abc123def456",
"name": "Order Notifications",
"url": "https://example.com/webhooks/atoship",
"secret": "whsec_a1b2c3d4e5f6...",
"_warning": "Save this secret securely!"
}事件类型
订阅特定事件，或使用 all 接收所有事件。查看详细的事件负载 →
面单事件
label.created已创建一张新的运输面单label.purchased面单已购买，可以使用label.voided面单已作废/取消label.refunded面单退款已处理完成追踪事件
tracking.created包裹已开始物流追踪tracking.updated追踪状态已更新tracking.delivered包裹已送达tracking.exception出现追踪异常（延误、退回等）批量事件
batch.created已创建一个新的批量操作batch.completed批量操作已成功完成batch.failed批量操作失败交运清单（SCAN Form）事件
scan_form.created已创建一份新的 SCAN 交运清单scan_form.updatedSCAN 交运清单状态已更新支付事件
payment.created已发起一笔支付/扣款payment.completed支付已成功完成payment.failed支付失败退货事件
return.created已创建退货面单/退货单（RMA）return.received仓库已收到退货return.completed退货已全部处理完成保险事件
insurance.purchased已为包裹购买保险insurance.cancelled保险已取消理赔事件
claim.created已提交一笔保险理赔claim.approved保险理赔已通过claim.rejected保险理赔被拒绝Webhook 负载格式
所有 webhook 负载都采用统一的格式，包含事件类型、时间戳和相关数据。
{
"id": "evt_abc123def456",
"object": "Event",
"type": "tracking.delivered",
"created_at": "2025-01-12T14:30:00.000Z",
"data": {
"object": {
"id": "lbl_xyz789",
"tracking_number": "9400111899223033005436",
"carrier": "USPS",
"status": "delivered",
"status_detail": "Package delivered to recipient",
"delivered_at": "2025-01-12T14:28:00.000Z",
"location": {
"city": "Los Angeles",
"state": "CA",
"zip": "90001"
}
},
"previous_attributes": {
"status": "out_for_delivery"
}
}
}负载字段
id- 唯一事件标识符type- 事件类型（例如 tracking.delivered）created_at- 事件发生的时间data.object- 受影响的资源对象data.previous_attributes- 发生变更的字段（如适用）
HTTP 请求头
X-Atoship-Signature- HMAC 签名X-Atoship-Event- 事件类型X-Atoship-Delivery- 投递尝试 IDContent-Type- application/json
验证 Webhook 签名
安全最佳实践
务必验证 webhook 签名，确保请求确实来自 Atoship 且未被篡改。 在生产环境中，切勿在未验证签名的情况下处理 webhook。
每个 webhook 都带有 X-Atoship-Signature 请求头， 其中包含使用你的 webhook 密钥对负载生成的 HMAC-SHA256 签名。
import crypto from 'crypto';
function verifyWebhookSignature(
payload: string,
signature: string,
secret: string
): boolean {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}
// Usage in your webhook handler
app.post('/webhooks/atoship', (req, res) => {
const signature = req.headers['x-atoship-signature'];
const payload = JSON.stringify(req.body);
if (!verifyWebhookSignature(payload, signature, WEBHOOK_SECRET)) {
return res.status(401).send('Invalid signature');
}
// Process the webhook...
const event = req.body;
console.log('Received event:', event.type);
res.status(200).send('OK');
});重试策略
如果你的端点返回非 2xx 状态码或请求超时，我们会重新投递该 webhook。
重试时间表
- • 第 1 次：立即
- • 第 2 次：1 分钟后
- • 第 3 次：5 分钟后
- • 第 4 次：30 分钟后
- • 第 5 次：2 小时后
成功判定标准
- • HTTP 状态码 200-299
- • 在超时时间内响应（默认 30 秒）
- • 成功建立连接
可配置选项
retry_attempts- 重试次数（0-10，默认 3）timeout- 请求超时时间，单位秒（5-60，默认 30）
最佳实践
应该做
- 立即返回 200，再异步处理
- 始终验证 webhook 签名
- 对重复事件进行幂等处理
- 仅使用 HTTPS 端点
- 记录 webhook 负载以便排查问题
不应该做
- 不要在响应前执行繁重的处理
- 不要忽略签名验证
- 不要假设事件会按顺序到达
- 不要使用 HTTP（非安全）端点
- 不要泄露你的 webhook 密钥
故障排查
API 参考
GET
/v1/webhooks列出所有 webhook 端点
POST
/v1/webhooks创建一个新的 webhook 端点
GET
/v1/webhooks/:id获取某个 webhook 端点
PATCH
/v1/webhooks/:id更新某个 webhook 端点
DELETE
/v1/webhooks/:id删除某个 webhook 端点
POST
/v1/webhooks/:id/test发送一条测试 webhook 以验证你的端点