> ## 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 Integration Model

> Understand signature validation, filtering, asynchronous processing, retries, and duplicate delivery in event-driven integrations.

Webhooks let a repository or CI/CD system notify PawSQL when a relevant event occurs. PawSQL validates the event, filters irrelevant payloads, and processes the review asynchronously.

## Goal

Understand signature validation, filtering, asynchronous processing, retries, and duplicate delivery in event-driven integrations.

## Prerequisites

No special prerequisites.

## Delivery flow

<Steps>
  <Step title="Event is produced">The source platform emits an event such as a push or merge request.</Step>
  <Step title="Signature is validated">PawSQL verifies the payload signature or shared secret and rejects invalid deliveries.</Step>
  <Step title="Payload is filtered">PawSQL ignores events outside the repository, branch, path, and event scope.</Step>
  <Step title="Job is created">A review job is queued with the workspace and policy mapped from the event.</Step>
  <Step title="Result is returned">The gate decision and report link are published to the source platform.</Step>
</Steps>

## Security model

* **Signature validation** — verify the shared secret or signing key on every delivery.
* **Replay protection** — record processed event identifiers and timestamps.
* **TLS** — require HTTPS and validate certificates.
* **Source allowlist** — accept deliveries only from expected sources and networks.
* **Secret handling** — store secrets in a managed vault; never log them.

## Retries and duplicate delivery

Source platforms may retry a delivery when the endpoint is unavailable or slow. PawSQL treats these as the same logical event:

* Duplicate deliveries are idempotent and do not create duplicate reviews or feedback.
* Retries are bounded; an event is recorded as failed after the platform's retry window.
* Endpoint errors follow the platform's retry policy and backoff.

## Filtering and processing

The review scope reduces noise and cost by limiting what the integration processes:

* Restrict repositories, branches, and event actions.
* Select SQL paths, file extensions, and database dialects.
* Ignore removed files and non-SQL changes.
* Map the event to the correct workspace and review policy.

## Operation notes

* Monitor delivery latency and the queue depth.
* Alert when the failure rate exceeds a threshold.
* Keep endpoint availability high to avoid triggering retries.
* Review processed event logs to confirm correct scope.

## Expected Result

A relevant event is validated, filtered, and processed into a review, with the gate decision and report link returned to the source platform.

## Verification

Confirm each delivery is signature-validated, replay-protected, and idempotent so duplicates do not create duplicate reviews.

## Related

* [Repository Connectors](/en/user-guide/cicd/repositories)
* [Troubleshoot CI/CD Integrations](/en/user-guide/cicd/logs-troubleshooting)