事件参考

全部 Webhook 事件类型的详细文档，包括载荷结构与触发条件。

← 返回 Webhooks 概览

事件概览

事件是 Webhook 通知的核心。每个事件都代表你 Atoship 账户中一次具体的操作或状态变更。理解事件载荷有助于你构建稳健可靠的集成。

事件结构

所有事件均遵循统一的结构，包含以下字段：

id

事件的唯一标识符（evt_xxx）

object

始终为 "Event"

type

事件类型（例如 "label.purchased"）

created_at

事件发生时的 ISO 8601 时间戳

data.object

受影响的资源及其当前状态

data.previous_attributes

发生变更的字段及其变更前的值（可选）

面单事件

与运输面单生命周期相关的事件

label.created

label

创建新运输面单但尚未购买时触发。

触发条件

通过 API 或控制台创建面单

载荷示例

{
  "id": "evt_abc123",
  "object": "Event",
  "type": "label.created",
  "created_at": "2025-01-12T10:00:00.000Z",
  "data": {
    "object": {
      "id": "lbl_xyz789",
      "object": "Label",
      "tracking_number": null,
      "carrier": "USPS",
      "service": "Priority Mail",
      "status": "draft",
      "from_address": {
        "name": "Sender Name",
        "street1": "123 Main St",
        "city": "Los Angeles",
        "state": "CA",
        "zip": "90001",
        "country": "US"
      },
      "to_address": {
        "name": "Recipient Name",
        "street1": "456 Oak Ave",
        "city": "New York",
        "state": "NY",
        "zip": "10001",
        "country": "US"
      },
      "parcel": {
        "weight": 16.0,
        "length": 10,
        "width": 8,
        "height": 4
      },
      "rate": {
        "amount": "8.95",
        "currency": "USD"
      },
      "created_at": "2025-01-12T10:00:00.000Z"
    }
  }
}

label.purchased

label

运输面单购买成功、可供使用时触发。

触发条件

支付完成并生成面单

载荷示例

{
  "id": "evt_def456",
  "object": "Event",
  "type": "label.purchased",
  "created_at": "2025-01-12T10:01:00.000Z",
  "data": {
    "object": {
      "id": "lbl_xyz789",
      "object": "Label",
      "tracking_number": "9400111899223033005436",
      "carrier": "USPS",
      "service": "Priority Mail",
      "status": "purchased",
      "label_url": "https://atoship.com/api/labels/lbl_xyz789.pdf",
      "label_format": "PDF",
      "cost": {
        "amount": "8.95",
        "currency": "USD"
      },
      "purchased_at": "2025-01-12T10:01:00.000Z"
    },
    "previous_attributes": {
      "status": "draft",
      "tracking_number": null
    }
  }
}

label.voided

label

运输面单被作废/取消时触发。

触发条件

通过 API 或控制台作废面单

载荷示例

{
  "id": "evt_ghi789",
  "object": "Event",
  "type": "label.voided",
  "created_at": "2025-01-12T12:00:00.000Z",
  "data": {
    "object": {
      "id": "lbl_xyz789",
      "object": "Label",
      "tracking_number": "9400111899223033005436",
      "status": "voided",
      "voided_at": "2025-01-12T12:00:00.000Z",
      "void_reason": "Customer request"
    },
    "previous_attributes": {
      "status": "purchased"
    }
  }
}

label.refunded

label

面单退款处理完成时触发。

触发条件

退款经承运商审批并处理完成

载荷示例

{
  "id": "evt_jkl012",
  "object": "Event",
  "type": "label.refunded",
  "created_at": "2025-01-15T10:00:00.000Z",
  "data": {
    "object": {
      "id": "lbl_xyz789",
      "object": "Label",
      "tracking_number": "9400111899223033005436",
      "status": "refunded",
      "refund": {
        "amount": "8.95",
        "currency": "USD",
        "refunded_at": "2025-01-15T10:00:00.000Z"
      }
    },
    "previous_attributes": {
      "status": "voided"
    }
  }
}

快速参考

事件类型	分类	说明
`label.created`	面单事件	创建新运输面单但尚未购买时触发。
`label.purchased`	面单事件	运输面单购买成功、可供使用时触发。
`label.voided`	面单事件	运输面单被作废/取消时触发。
`label.refunded`	面单事件	面单退款处理完成时触发。
`tracking.created`	物流追踪事件	为某个运输开始追踪时触发。
`tracking.updated`	物流追踪事件	追踪状态发生变化时触发。
`tracking.delivered`	物流追踪事件	包裹成功送达时触发。
`tracking.exception`	物流追踪事件	发生物流异常（延误、退回寄件人等）时触发。
`batch.created`	批量事件	创建新的批量操作时触发。
`batch.completed`	批量事件	批量操作成功完成时触发。
`batch.failed`	批量事件	批量操作彻底失败时触发。
`scan_form.created`	SCAN 揽收单事件	创建新的 SCAN 揽收单时触发。
`scan_form.updated`	SCAN 揽收单事件	SCAN 揽收单状态更新时触发。
`payment.created`	支付事件	发起支付/扣款时触发。
`payment.completed`	支付事件	支付成功完成时触发。
`payment.failed`	支付事件	支付失败时触发。
`return.created`	退货事件	创建退货面单或 RMA 时触发。
`return.received`	退货事件	退货包裹在仓库签收时触发。
`return.completed`	退货事件	退货全部处理完成时触发。
`insurance.purchased`	保险事件	为某个运输购买保险时触发。
`insurance.cancelled`	保险事件	保险被取消时触发。
`claim.created`	理赔事件	提交保险理赔时触发。
`claim.approved`	理赔事件	保险理赔获批时触发。
`claim.rejected`	理赔事件	保险理赔被拒绝时触发。