Webhook 事件

概述

Webhook 允许您在 Curosa 平台发生事件时接收实时通知。当事件发生时，我们会向订阅了该事件的每个活动 Webhook URL 发送一个 HTTP POST 请求。这使您能够将您的系统与 Curosa 集成并自动响应事件。

Webhook 交付

当事件发生时，我们会向每个处于活动状态并订阅了该事件的 Webhook URL 发送一次 HTTP POST 请求。

请求格式

属性	值
方法	`POST`
URL	您配置的 Webhook URL
请求头	`Content-Type: application/json`
请求体	JSON 对象（见下文）

请求体结构

每个 Webhook 请求体都遵循以下一致的结构：

字段	类型	描述
`event`	string	事件标识符（例如 `NewOrderCreated`）。使用此字段来路由或处理事件。
`data`	object	特定事件的负载。结构取决于 `event` 类型（请参阅下文的事件详情）。
`timestamp`	string	发送请求时的 ISO 8601 日期时间（例如 `2026-02-05T14:30:00.000000Z`）。

可用事件

NewOrderCreated

当创建包含您的产品的新客户订单时发送。每个订单发送一次 Webhook 调用（因此，一个包含多个供应商订单的订单组将为每个供应商订单触发一次调用）。

事件标识符： "NewOrderCreated"

数据结构：

路径	类型	描述
`data.order`	object	已创建的订单
`data.order.id`	integer	内部订单 ID
`data.order.order_number`	string \| null	人类可读的订单编号（如果已设置）
`data.order.status`	string	订单状态（例如 `pending`）
`data.order.allocation_status`	string	库存分配状态（例如 `unallocated`, `allocated`）
`data.order.currency`	string	货币代码（例如 `GBP`）
`data.order.items_cost_total`	number	订单中商品的总成本
`data.order.created_at`	string \| null	订单创建时的 ISO 8601 日期时间
`data.customer`	object \| null	与订单关联的客户，如果未设置则为 `null`
`data.customer.id`	integer	内部客户 ID
`data.customer.name`	string	客户显示名称

示例请求：

{
  "event": "NewOrderCreated",
  "data": {
    "order": {
      "id": 12345,
      "order_number": "ORD-2026-001234",
      "status": "pending",
      "allocation_status": "unallocated",
      "currency": "GBP",
      "items_cost_total": 150.00,
      "created_at": "2026-02-05T14:30:00.000000Z"
    },
    "customer": {
      "id": 678,
      "name": "Jane Smith"
    }
  },
  "timestamp": "2026-02-05T14:30:01.000000Z"
}

Webhook 交付与重试

异步交付：Webhook 是异步发送的（通过队列）。事件发生后出现轻微延迟是正常的。
交付状态：交付状态（例如最近一次成功或失败）目前未在 UI 中展示。
重试行为：如果您的端点返回非 2xx 状态码或我们无法连接（例如超时），我们会记录失败，并可能根据我们的队列配置进行重试。

处理未知事件

未来可能会添加更多事件。您的 Webhook 端点应设计为：

优雅地忽略未知的 event 值，或者
记录未知事件以用于支持和调试目的

这可以确保在 API 引入新事件类型时，您的集成保持稳定。