Legitmark 发送三种事件类型。每个 Webhook 目标地址自动接收所有事件。
state_change
当服务请求转换到新状态时发送。这是跟踪鉴定进度和结果的主要事件。
Payload
{
"event_type": "state_change",
"sr_uuid": "b16c763b-1723-455d-ba29-164418044886",
"reference_id": "YOUR-INTERNAL-ITEM-ID",
"state": {
"primary": "COMPLETE",
"supplement": "APPROVED"
},
"timestamp": "2026-02-10T12:00:00.000Z"
}
您的内部商品 ID — 创建服务请求时设置的 external_id。
状态转换
下表列出了您应该处理的最常见状态转换：
state.primary | state.supplement | 含义 |
|---|
QC | PENDING | 照片已提交，正在质量审核中 |
QC | REJECTED | 照片未通过质量审核 — 随后会收到包含详情的 media_rejected 事件 |
QC | APPROVED | 照片通过质量审核，鉴定开始 |
UNDERWAY | ASSIGNED | 鉴定师已分配 |
COMPLETE | APPROVED | 商品为正品 |
COMPLETE | REJECTED | 商品非正品 |
最重要的状态转换是 COMPLETE + APPROVED 或 COMPLETE + REJECTED — 这是最终鉴定结果。参阅服务请求状态了解完整的状态机。使用 TypeScript SDK（v0.2.0+），您可以使用 isAuthentic(event) 和 isCounterfeit(event) 来检查这些状态，而无需手动比较字符串。参阅 Webhook 处理指南。
当上传的图片未通过质量审核时发送。每张被拒绝的图片都包含面名称和拒绝原因，以便您提示用户重新上传特定照片。
Payload
{
"event_type": "media_rejected",
"sr_uuid": "b16c763b-1723-455d-ba29-164418044886",
"reference_id": "YOUR-INTERNAL-ITEM-ID",
"sides": [
{
"side": "Front",
"reason": "图像模糊",
"message": "提交的图像太模糊。请拍摄更清晰的照片，确保最小的运动以提高准确性。"
},
{
"side": "Interior",
"reason": "光线不足",
"message": "提交的图像光线不足。请拍摄一张光线更好的新照片以提高可见度。"
}
],
"timestamp": "2026-02-10T12:15:00.000Z"
}
被拒绝图片及原因的数组。
被拒绝面的名称（例如 "Front"、"Label"、"Back"）。
拒绝原因。这些是来自 Legitmark 原因数据库的人类可读字符串（例如 "图像模糊"、"光线不足"）。随着新原因的添加，值可能会变化。
收到 media_rejected 事件时，用户需要重新上传被拒绝的特定面的图片，服务请求才能继续。请使用 side 名称和 message 提示用户，以提供最佳体验。
使用 TypeScript SDK，needsResubmission(event) 对此事件类型返回 true。参阅 Webhook 处理指南。
invalidate_sr
当服务请求被取消时发送。
Payload
{
"event_type": "invalidate_sr",
"sr_uuid": "b16c763b-1723-455d-ba29-164418044886",
"reference_id": "YOUR-INTERNAL-ITEM-ID",
"invalidation_reason": {
"code": "CANCELLED",
"message": "Service request cancelled"
},
"timestamp": "2026-02-10T14:30:00.000Z"
}
显示 invalidation_reason 属性
原因代码。目前固定为 "CANCELLED"。未来可能会增加其他代码。
目前为 "Service request cancelled"。具体的取消原因会通过邮件单独通知最终用户。
