跳转到主要内容
本指南介绍如何构建可靠的 Webhook 处理程序，包含多种语言的代码示例和生产环境建议。

​
使用 TypeScript SDK

如果您使用 TypeScript SDK（v0.2.0+），SDK 提供类型化的 Payload 和辅助函数来处理事件解析和状态检查。 
import {
  parseWebhookEvent,
  isAuthentic,
  isCounterfeit,
  needsResubmission,
  isCancelled,
} from 'legitmark';

app.post('/webhooks/legitmark', express.json(), (req, res) => {
  const event = parseWebhookEvent(req.body);

  if (isAuthentic(event)) {
    markItemAsAuthentic(event.reference_id);
  } else if (isCounterfeit(event)) {
    flagItem(event.reference_id);
  } else if (needsResubmission(event)) {
    requestNewPhotos(event.reference_id, event.sides);
  } else if (isCancelled(event)) {
    closeCase(event.sr_uuid);
  }

  res.status(200).send('OK');
});
parseWebhookEvent() 验证 Payload 结构并返回类型化的 LegitmarkWebhookEvent。辅助函数检查特定的状态组合：
辅助函数返回 true 的条件
isAuthentic(event)COMPLETE + APPROVED — 商品为正品
isCounterfeit(event)COMPLETE + REJECTED — 商品非正品
isCancelled(event)CANCELLED — 请求已取消
needsResubmission(event)media_rejected — 图片需要重新上传
isQcApproved(event)QC + APPROVED — 照片通过质量审核
isAuthenticationInProgress(event)UNDERWAY + ASSIGNED — 鉴定师正在工作

​
基础处理程序

如果您未使用 TypeScript SDK，以下是多种语言的示例。 
app.post('/webhooks/legitmark', express.json(), (req, res) => {
  const event = req.body;

  switch (event.event_type) {
    case 'state_change':
      if (event.state.primary === 'COMPLETE') {
        updateAuthResult(event.reference_id, event.state.supplement);
      }
      break;

    case 'media_rejected':
      event.sides.forEach(side => {
        flagImageForReupload(event.reference_id, side.side, side.reason);
      });
      break;

    case 'invalidate_sr':
      cancelItem(event.reference_id, event.invalidation_reason.message);
      break;
  }

  res.status(200).send('OK');
});

​
最佳实践

尽快确认 Webhook。如果处理逻辑复杂或需要调用外部服务，请先将任务加入队列并返回 200。
您可能会多次收到同一事件。根据 Payload 字段构建去重键：
  • state_change：sr_uuid + state.primary + state.supplement（同一 SR 会发出多次状态变更）
  • media_rejected：sr_uuid + event_type
  • invalidate_sr：sr_uuid + event_type
在生产环境中，请使用持久化存储（数据库、Redis）进行去重。
保存完整的 Webhook Payload 用于调试。出现问题时，拥有原始数据可以大大加快诊断速度。
不要拒绝包含未识别 event_type 值的 Webhook。未来可能会添加新的事件类型。对任何事件都返回 200。

​
总结

您的 Webhook 处理程序应当：
  • 使用 HTTPS 端点 并在 30 秒内返回 200
  • 保证 幂等性 — 使用 Payload 字段进行去重（不仅仅使用 sr_uuid，因为一个 SR 会发出多个事件）
  • 接受未知事件类型 而不报错（未来可能会添加新事件）
  • 异步处理 复杂逻辑以避免超时