Back to Details

planetscale-webhook-automation-recommendations

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Webhook automation recommendations

Webhook自动化方案推荐

Purpose

目的

Review and recommend PlanetScale webhooks that notify humans and trigger safe automation. Do not create or update webhooks without approval.
审核并推荐可通知人员、触发安全自动化的PlanetScale Webhook。未经批准不得创建或更新Webhook。

Webhook design principle

Webhook设计原则

Webhooks may trigger automation, but automation must produce recommendations, issues, branches, or pull requests by default. It must not directly mutate production databases or production application behavior without explicit human approval.
Webhook可触发自动化操作，但默认情况下，自动化操作仅应生成建议、问题工单、分支或拉取请求（PR）。未经明确人工批准，不得直接修改生产数据库或变更生产应用行为。

Events to evaluate

需评估的事件

General and Postgres

通用与Postgres相关事件

  • branch.anomaly
    : new Insights anomaly.
  • branch.out_of_memory
    : Postgres out-of-memory event.
  • branch.primary_promoted
    : primary failover/promotion.
  • branch.ready
    : branch created and ready.
  • branch.sleeping
    : branch sleeping.
  • branch.start_maintenance
    : maintenance starting.
  • cluster.storage
    : storage threshold or growth event.
  • database.access_request
    : access request.
  • branch.schema_recommendation
    : schema recommendation event when available.
  • webhook.test
    : test event.
  • branch.anomaly
    : 新的Insights异常。
  • branch.out_of_memory
    : Postgres内存不足事件。
  • branch.primary_promoted
    : 主节点故障转移/晋升事件。
  • branch.ready
    : 分支创建完成并就绪。
  • branch.sleeping
    : 分支进入休眠状态。
  • branch.start_maintenance
    : 维护即将开始。
  • cluster.storage
    : 存储阈值触发或存储增长事件。
  • database.access_request
    : 访问请求事件。
  • branch.schema_recommendation
    : 可用时触发的Schema建议事件。
  • webhook.test
    : 测试事件。

Vitess deploy lifecycle

Vitess部署生命周期事件

  • deploy_request.opened
  • deploy_request.queued
  • deploy_request.in_progress
  • deploy_request.pending_cutover
  • deploy_request.schema_applied
  • deploy_request.errored
  • deploy_request.reverted
  • deploy_request.closed
  • keyspace.storage
  • deploy_request.opened
  • deploy_request.queued
  • deploy_request.in_progress
  • deploy_request.pending_cutover
  • deploy_request.schema_applied
  • deploy_request.errored
  • deploy_request.reverted
  • deploy_request.closed
  • keyspace.storage

Recommended routing

推荐路由方案

Human alerting

人工告警路由

Send these to incident or operations channels:
  • branch.anomaly
  • branch.out_of_memory
  • branch.primary_promoted
  • branch.start_maintenance
  • cluster.storage
  • keyspace.storage
  • deploy_request.errored
  • deploy_request.reverted
将以下事件发送至事件响应或运维渠道：
  • branch.anomaly
  • branch.out_of_memory
  • branch.primary_promoted
  • branch.start_maintenance
  • cluster.storage
  • keyspace.storage
  • deploy_request.errored
  • deploy_request.reverted

Engineering notification

工程通知路由

Send these to Slack, Linear/Jira, or deployment channels:
  • deploy_request.opened
  • deploy_request.queued
  • deploy_request.in_progress
  • deploy_request.pending_cutover
  • deploy_request.schema_applied
  • deploy_request.closed
  • branch.schema_recommendation
将以下事件发送至Slack、Linear/Jira或部署相关渠道：
  • deploy_request.opened
  • deploy_request.queued
  • deploy_request.in_progress
  • deploy_request.pending_cutover
  • deploy_request.schema_applied
  • deploy_request.closed
  • branch.schema_recommendation

Agent intake queue

Agent处理队列路由

Send these to an agent-safe workflow:
  • branch.anomaly
  • branch.schema_recommendation
  • deploy_request.errored
  • cluster.storage
  • keyspace.storage
Agent output may include, without approval:
  • Triage summary, probable cause, linked Insights/query patterns.
  • Recommended schema, code, Traffic Control, or operational change.
  • Pull request against application code.
  • Development branch with DDL or migration applied.
  • Open deploy request into a review-protected branch.
  • Issue or ticket.
Agent output must not cross the review gate on its own: no production deploys, PR merges, Traffic Control enforcement, credential rotation, or network changes — those require human action or a standing authorization per 
../13-autonomous-execution-mode/SKILL.md
.
将以下事件发送至Agent安全工作流：
  • branch.anomaly
  • branch.schema_recommendation
  • deploy_request.errored
  • cluster.storage
  • keyspace.storage
在无需批准的情况下，Agent输出可包含：
  • 分类汇总、可能原因、关联的Insights/查询模式。
  • 推荐的Schema、代码、流量控制或运维变更方案。
  • 针对应用代码的拉取请求（PR）。
  • 已应用DDL或迁移的开发分支。
  • 向受保护分支发起的部署请求。
  • 问题工单。
Agent输出不得自行越过审核关卡：不得进行生产部署、PR合并、流量控制生效、凭证轮换或网络变更——这些操作需要人工干预或依据
../13-autonomous-execution-mode/SKILL.md
中的长期授权执行。

Webhook receiver requirements

Webhook接收端要求

Recommend only receivers that meet these requirements:
  • HTTPS endpoint.
  • Fast 2xx response; expensive work is queued asynchronously.
  • No dependency on following redirects.
  • Signature verification using PlanetScale webhook signature header and the webhook secret.
  • Idempotency by event ID or timestamp/resource tuple.
  • Dead-letter queue or retry-safe logging.
  • Human-readable audit trail.
  • Clear owner and escalation path.
  • Secret rotation procedure.
仅推荐满足以下要求的接收端：
  • HTTPS端点。
  • 快速返回2xx响应；耗时操作需异步入队处理。
  • 不依赖重定向跳转。
  • 使用PlanetScale Webhook签名头和Webhook密钥进行签名验证。
  • 依据事件ID或时间戳/资源元组实现幂等性。
  • 具备死信队列或可重试的安全日志机制。
  • 可阅读的审计追踪记录。
  • 明确的负责人和升级路径。
  • 密钥轮换流程。

Recommended automation flows

推荐自动化流程

Anomaly to PR flow

异常转PR流程

  1. Receive 
    branch.anomaly
    .
  2. Verify signature.
  3. Queue job.
  4. Fetch anomaly details and relevant Insights query patterns.
  5. Locate code path by SQLCommenter tags and repository search.
  6. Classify as schema, code, Traffic Control, or unknown.
  7. Generate report and optional PR.
  8. Ask human to approve database-affecting work.
  1. 接收
    branch.anomaly
    事件。
  2. 验证签名。
  3. 将任务入队。
  4. 获取异常详情及相关Insights查询模式。
  5. 通过SQLCommenter标签和代码库搜索定位代码路径。
  6. 分类为Schema问题、代码问题、流量控制问题或未知类型。
  7. 生成报告及可选的PR。
  8. 请求人工批准影响数据库的操作。

Schema recommendation to branch/deploy flow

Schema建议转分支/部署流程

—

Vitess环境：

For Vitess:
  1. Receive 
    branch.schema_recommendation
    .
  2. Fetch recommendation details.
  3. Apply the DDL to a development branch.
  4. Open a pull request with fingerprint, metrics, and expected effect.
  5. Open the deploy request — the DR and PR together are the reviewable unit; opening them requires no approval.
  6. Deploy on human approval, or autonomously under a standing authorization that allowlists this deploy class (
    ../13-autonomous-execution-mode/SKILL.md
    ).
For Postgres:
  1. Receive 
    branch.schema_recommendation
    .
  2. Fetch recommendation details.
  3. Convert DDL to application migration.
  4. Test on a non-production branch and record the result in the PR.
  5. Open PR.
  6. Apply to production on merge via the deployment pipeline, or on explicit approval where no pipeline exists.
  1. 接收
    branch.schema_recommendation
    事件。
  2. 获取建议详情。
  3. 将DDL应用至开发分支。
  4. 发起包含指纹、指标及预期效果的PR。
  5. 发起部署请求——部署请求（DR）与PR共同构成可审核单元，发起操作无需批准。
  6. 经人工批准后部署，或在允许此类部署的长期授权下自动部署（参考
    ../13-autonomous-execution-mode/SKILL.md
    ）。

Deploy request lifecycle flow for Vitess

Postgres环境：

  • Notify when opened.
  • Validate owner and linked application PR.
  • Alert when queued or in progress.
  • Alert strongly when errored or reverted.
  • Notify pending cutover and require owner acknowledgement for gated deployments.
  • Record schema applied and correlate with application deploy.
  1. 接收
    branch.schema_recommendation
    事件。
  2. 获取建议详情。
  3. 将DDL转换为应用迁移脚本。
  4. 在非生产分支测试并将结果记录至PR。
  5. 发起PR。
  6. 合并后通过部署流水线应用至生产环境，或在无流水线时经明确批准后应用。

Anti-patterns to block

Vitess部署请求生命周期流程

Do not recommend:
  • Webhook directly runs production DDL, bypassing the PR/deploy-request workflow. (Driving the DDL through a branch, PR, and deploy request is the supported pattern, not an anti-pattern.)
  • Webhook applies schema recommendations straight to production with no reviewable artifact.
  • Webhook directly enforces Traffic Control.
  • Webhook directly changes IP restrictions.
  • Webhook directly rotates credentials.
  • Webhook posts secrets or raw SQL with literals into public Slack channels.
  • Webhook receiver ignores signature verification.
  • Webhook receiver does long-running work before returning 2xx.
  • 部署请求发起时发送通知。
  • 验证负责人及关联的应用PR。
  • 部署请求入队或进行中时发送告警。
  • 部署请求出错或回滚时发送强告警。
  • 通知切换准备状态， gated部署需负责人确认。
  • 记录Schema应用情况并与应用部署关联。

Output

需规避的反模式

Return:
  • Existing webhook inventory.
  • Missing recommended subscriptions.
  • Destination quality review.
  • Signature verification status.
  • Automation opportunities.
  • Unsafe automation risks.
  • Proposed webhook changes requiring approval.
End with:
“No webhooks or automation endpoints have been created, updated, or deleted.”
不得推荐以下方案：
  • Webhook直接执行生产环境DDL，绕过PR/部署请求流程。（通过分支、PR和部署请求执行DDL是受支持的模式，不属于反模式。）
  • Webhook将Schema建议直接应用至生产环境，无任何可审核的工件。
  • Webhook直接强制执行流量控制。
  • Webhook直接修改IP限制。
  • Webhook直接轮换凭证。
  • Webhook将密钥或带字面量的原始SQL发布至公开Slack频道。
  • Webhook接收端忽略签名验证。
  • Webhook接收端在返回2xx响应前执行长时间运行的操作。
—

输出内容

—
返回：
  • 现有Webhook清单。
  • 缺失的推荐订阅项。
  • 目标渠道质量审核结果。
  • 签名验证状态。
  • 自动化机会。
  • 不安全自动化风险。
  • 需批准的Webhook变更提案。
结尾需包含：
“未创建、更新或删除任何Webhook或自动化端点。”