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

> ## Agent Instructions
> PawSQL 是一个产品：Cloud 是公网部署形态，Engine / Optimizer / Auditor / Advisor / Patroller 是同一产品的组件与交付形态，不是彼此独立的产品。 / PawSQL is a single product: Cloud is the public deployment form, while Engine / Optimizer / Auditor / Advisor / Patroller are components and delivery forms of the same product, not separate products.
> 术语以站内术语表为准：SQL 审核对应英文 SQL Review，查询重写对应 Query Rewrite，索引推荐对应 Index Recommendation；英文内容统一用 Review，不用 Audit。 / Use the site glossary for terminology: 审核 is SQL Review, 重写 is Query Rewrite, 索引推荐 is Index Recommendation; English content uses Review, never Audit.
> 引用能力范围或版本支持时以对应页面为准；标注 unknown、或 status 非 published 的内容表示尚未经产品核实，不应作为事实引用。 / Cite capability scope and version support from the corresponding page; content marked unknown, or with a status other than published, is not yet product-verified and must not be cited as fact.

# Webhook 集成机制

> 了解事件驱动集成中的签名、过滤、异步处理、重试和重复事件控制。

Webhook 是预置代码仓库连接器和企业定制集成常用的事件通知机制。平台向 PawSQL 或企业集成服务发送事件，由接收方解析仓库、提交、分支和变更信息。

## 目标

了解事件驱动集成中的签名、过滤、异步处理、重试和重复事件控制。

## 准备工作

无特殊前置条件。

## 适用事件

| 事件                           | 建议用途             |
| ---------------------------- | ---------------- |
| Push                         | 检查进入受控分支的 SQL 变更 |
| Pull Request / Merge Request | 在合并前执行质量门禁       |
| Reopen / Synchronize         | 提交更新后重新审核        |
| Merge                        | 记录最终状态或触发发布前复核   |
| 手工重放                         | 排障或策略更新后重新执行     |

## 配置流程

<Steps>
  <Step title="创建集成配置">
    在 PawSQL 或企业集成服务中确定目标项目、工作空间、审核策略和允许的仓库。
  </Step>

  <Step title="生成地址和密钥">
    获取 Webhook 接收地址并生成独立密钥。不同仓库或环境不应共用无法追踪的凭据。
  </Step>

  <Step title="配置仓库事件">
    在代码平台中填写地址和密钥，选择 Push 或合并请求等需要的事件。
  </Step>

  <Step title="设置过滤条件">
    限定分支、目录、文件扩展名和事件动作，减少无效工单。
  </Step>

  <Step title="发送测试事件">
    确认请求被接收、签名验证成功，并能够创建对应 PawSQL 工单。
  </Step>

  <Step title="验证结果回传">
    检查提交状态、合并请求评论或流水线结果是否包含正确的工单链接和结论。
  </Step>
</Steps>

## 安全要求

* 仅接受 HTTPS 请求；
* 校验平台提供的签名或共享密钥；
* 限制请求体大小并设置合理超时；
* 记录事件 ID，但不在日志中保存凭据和完整敏感 SQL；
* 对允许的仓库、组织和事件类型执行白名单检查；
* 定期轮换密钥，并为轮换保留短暂的双密钥窗口。

## 重试与重复事件

Webhook 发送方可能因超时重复投递事件。接收方应以平台事件 ID 为首选幂等键；没有事件 ID 时，可组合平台、仓库、提交、事件动作和策略版本生成稳定标识。

<Warning>
  Webhook 返回成功只表示事件已被接收，不代表 SQL 审核已经完成。长时间分析应异步执行，并通过工单查询或回调获取最终结果。
</Warning>

## 验证结果

成功接入后，应能从一次测试事件追踪到代码提交、PawSQL 工单、审核策略、门禁结论和结果回传记录。若任一关联缺失，请参阅[CI/CD 集成故障排查](/user-guide/cicd/logs-troubleshooting)。