> ## Documentation Index
> Fetch the complete documentation index at: https://docs.legitmark.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks 简介

> 当鉴定状态变更、图片被拒绝或服务请求被作废时，接收实时通知。

Legitmark 通过 Webhook 向您的 HTTPS 端点发送实时事件通知。当服务请求状态变更、图片在质量审核中被拒绝或请求被作废时，您的端点将收到包含事件数据的 `POST` 请求。

消息投递支持自动重试和指数退避。

<Note>
  需要设置 Webhook 目标地址？请按照[入门指南](/cn/partner/getting-started)中的步骤操作。
</Note>

## 要求

您的 Webhook 端点必须满足以下要求：

| 要求         | 详情                                                                       |
| ---------- | ------------------------------------------------------------------------ |
| **HTTPS**  | 目标 URL 必须使用 HTTPS                                                        |
| **200 响应** | 在 30 秒内返回 `200` 状态码以确认收到                                                 |
| **幂等性**    | 处理重复投递 — 参阅 [Webhook 处理指南](/cn/webhook-reference/handling) 了解每种事件类型的去重策略 |

## 事件类型

所有目标地址自动接收全部事件类型，不支持按事件过滤。

<CardGroup cols={3}>
  <Card title="state_change" icon="arrows-rotate" href="/cn/webhook-reference/events#state_change">
    服务请求状态变更 — 质量审核、鉴定进度或最终结果。
  </Card>

  <Card title="media_rejected" icon="image-slash" href="/cn/webhook-reference/events#media_rejected">
    上传的图片在质量审核中被拒绝。
  </Card>

  <Card title="invalidate_sr" icon="circle-xmark" href="/cn/webhook-reference/events#invalidate_sr">
    服务请求被取消或无法处理。
  </Card>
</CardGroup>

## 通用 Payload 字段

每个 Webhook 事件都包含以下基础字段：

| 字段             | 类型               | 说明                                                     |
| -------------- | ---------------- | ------------------------------------------------------ |
| `event_type`   | `string`         | 事件标识符（`state_change`、`media_rejected`、`invalidate_sr`） |
| `sr_uuid`      | `string`         | 服务请求 UUID                                              |
| `reference_id` | `string \| null` | 您的内部商品 ID（创建服务请求时设置的 `external_id`）                    |
| `timestamp`    | `string`         | 事件发生时的 ISO 8601 时间戳                                    |

## 重试机制

投递失败（非 2xx 响应或超时）将通过指数退避策略自动重试：

| 尝试次数 | 延迟      |
| ---- | ------- |
| 1    | 立即      |
| 2    | 约 5 秒   |
| 3    | 约 5 分钟  |
| 4    | 约 30 分钟 |
| 5    | 约 2 小时  |

所有重试用尽后，消息将被标记为失败。您可以在 [Legitmark 控制台](https://app.legitmark.com/settings/developer)中查看投递状态并手动重试。

## 测试

如果您还没有准备好端点，可以使用 [Svix Play](https://play.svix.com/) 生成一个临时的 Webhook URL 用于测试。将生成的 URL 作为 Webhook 目标地址粘贴到[开发者设置](https://app.legitmark.com/settings/developer)中，发送测试事件，然后实时查看 Payload。

## 后续步骤

<CardGroup cols={2}>
  <Card title="事件类型" icon="bolt" href="/cn/webhook-reference/events">
    每种事件类型的详细 Payload 结构。
  </Card>

  <Card title="Webhook 处理指南" icon="code" href="/cn/webhook-reference/handling">
    代码示例、最佳实践和安全指南。
  </Card>
</CardGroup>