Webhook 事件类型
Webhook 让你在 atoship 账户中发生事件时，实时收到通知。 配置 Webhook 端点即可监听你关心的特定事件类型。
签名验证
每一个 Webhook 请求都会带上签名请求头，用于验证真伪。请使用你的 Webhook 密钥， 对原始请求体计算 HMAC-SHA256，以此校验签名。
X-Atoship-Signature: sha256=abc123...可用事件
面单事件
与运单标签生命周期相关的事件
label.created成功购买新的运单标签时触发
label.voided运单标签被作废/取消时触发
label.refunded面单退款处理完成时触发
物流追踪事件
与包裹追踪状态更新相关的事件
tracking.updated货件的追踪状态发生变化时触发
tracking.delivered包裹成功签收送达时触发
tracking.exception出现派送异常时触发
tracking.return_to_sender包裹被退回寄件人时触发
保险事件
与运输保险相关的事件
insurance.purchased为货件购买保险时触发
insurance.claim.filed提交保险理赔申请时触发
insurance.claim.approved保险理赔申请通过时触发
insurance.claim.denied保险理赔申请被拒绝时触发
退货事件
与退货货件相关的事件
return.created创建退货面单时触发
return.in_transit退货包裹在途运输时触发
return.received退货包裹签收入库时触发
账户事件
与账户和计费相关的事件
account.balance.low账户余额低于阈值时触发
account.balance.depleted账户余额归零时触发
最佳实践
快速响应
在 30 秒内返回 200 状态码，以确认已收到通知
处理重复通知
利用事件 ID 对事件进行去重
验证签名
务必在处理前先校验 Webhook 签名
重试处理
失败的 Webhook 最多会以指数退避的方式重试 5 次
WEBHOOK
事件负载结构| 1 | { |
| 2 | "id": "evt_1234567890", |
| 3 | "object": "Event", |
| 4 | "type": "label.created", |
| 5 | "created_at": "2025-01-14T10: 00: 00Z", |
| 6 | "data": { |
| 7 | "id": "lbl_k7x9m2p4q8r5", |
| 8 | "object": "Label", |
| 9 | "status": "purchased", |
| 10 | "tracking_number": "9400111899223456789012", |
| 11 | "carrier": "USPS", |
| 12 | "service": "Priority Mail", |
| 13 | "rate": 8.95, |
| 14 | "currency": "USD" |
| 15 | } |
| 16 | } |
请求头
Content-Type:application/json
X-Atoship-Signature:sha256=...
X-Atoship-Event:label.created
X-Atoship-Delivery-ID:dlv_abc123
重试计划
第 1 次立即
第 2 次5 分钟后
第 3 次30 分钟后
第 4 次2 小时后
第 5 次24 小时后