aatuh/webhookery

# Webhookery [](https://github.com/aatuh/webhookery/actions/workflows/ci.yml) [](https://github.com/aatuh/webhookery/actions/workflows/security.yml) [](https://github.com/aatuh/webhookery/actions/workflows/integration.yml) [](https://github.com/aatuh/webhookery/actions/workflows/fuzz.yml) [](https://github.com/aatuh/webhookery/actions/workflows/codeql.yml) [](https://github.com/aatuh/webhookery/actions/workflows/scorecard.yml) [](https://github.com/aatuh/webhookery/actions/workflows/release.yml) [](LICENSE)      审计级别的 webhook 捕获、重放与证据——支持自托管。 Webhookery 在确认收到提供商的 webhook 之前，会对其进行持久化捕获， 验证签名，记录交付尝试，支持受控的重放，并在集成失败时 导出可验证的证据。 网站： 该产品的承诺在设计上非常明确：Webhookery 在完成持久化捕获之前绝不返回入站 成功；数据丢失的边界必须清晰明确；且重放、 恢复和审计证据必须作为核心一等公民功能。它专为那些需要证明什么数据到达、什么 失败、什么被重放以及保留了什么证据的团队而构建，而不是自欺欺人地认为交付可以是“恰好一次”（exactly once）的。 如果您正在评估 Webhookery，请从这里开始： - 为什么选择 Webhookery：`docs/why-webhookery.md` - 评估者演练：`docs/evaluator-quickstart.md` - 本地证据演示：`examples/webhook-evidence-demo/` - Stripe 验证指南：`docs/live-provider-proof/stripe.md` - GitHub 验证指南：`docs/live-provider-proof/github.md` - Shopify 验证指南：`docs/live-provider-proof/shopify.md` - 静态产品页面：`site/index.html` - 渲染的 OpenAPI 参考：`docs/openapi/index.html` - API 契约矩阵：`docs/reference/api-contract-matrix.md` - 发行说明：`docs/releases/v0.2.0-pilot.md` - 发行证据索引：`docs/reference/release-evidence-index.md` - 当前公开发行的元数据：`release/current.json` - 之前的发行说明：`docs/releases/v0.1.0-rc1.md` - 试点拓扑：`docs/pilot-topology.md` - 商业评估：`docs/commercial-evaluation.md` ## 实现状态 本仓库包含实际实现。当前代码库包括： - `cmd/` 下的 Go API、worker、scheduler 和 `whcp` CLI 入口点。 - `internal/` 下的领域、应用、HTTP、持久化、provider、交付、审计链、 SSRF、重试、转换和配置代码。 - `pkg/client` 和 `pkg/verifier` 下的公共辅助包。 - 作为规范 REST 契约的 `openapi.yaml`，其中 `sdk/openapi.yaml` 是 已提交的适配 SDK 的副本，而 `docs/openapi/index.html` 是渲染后的 参考工件。 - `migrations/` 下的 PostgreSQL 迁移脚本。 - Docker Compose、Kubernetes、Helm 和 Terraform 部署配置。 - SDK 工件、Postman 和 Bruno 冒烟测试集合，以及 CI 工作流。 `.initial_design.md` 是历史的设计输入和架构基本原理。它 不能证明已实现的行为。请以代码、OpenAPI、迁移脚本、部署 配置和规范文档作为当前行为的真实依据。 ## 本地快速开始 前置条件：Go、Docker 和 Docker Compose。 对于“证据优先”的路径，请运行支付失败演示： ``` docker compose up -d postgres export WEBHOOKERY_TEST_DATABASE_URL='postgres://webhookery:change-me@localhost:5432/webhookery?sslmode=disable' examples/webhook-evidence-demo/run.sh ``` 预期结果：`examples/webhook-evidence-demo/output/` 包含经过脱敏处理的 事件报告、证据清单、验证输出，以及针对 失败下游交付并进行重放的本地证据 包。 对于简短的 API 冒烟测试路径： ``` cp .env.example .env docker compose up --build ``` 在另一个 shell 中： ``` curl -fsS http://localhost:8080/readyz export WEBHOOKERY_API_KEY=dev-bootstrap-key go run ./cmd/whcp events list --api-key "$WEBHOOKERY_API_KEY" go run ./cmd/whcp audit verify-chain --api-key "$WEBHOOKERY_API_KEY" ``` 预期结果：就绪检查返回成功，CLI 能够使用 本地引导密钥进行身份验证，并且审计链验证返回 JSON 结果。 本地引导密钥仅供开发使用。在任何 类生产环境使用之前，请立即创建基于数据库的 API 密钥，并删除或轮换引导哈希。 请使用 `docs/evaluator-quickstart.md` 获取引导式的证据闭环演练、 预期输出、故障排除和非承诺声明。 ## 简短的冒烟测试路径 - 本地 API 和 worker：`docker compose up --build`，然后访问 `/readyz`。 - 非变更性文档和契约门禁：`make docs-check`。 - 提供商一致性矩阵和本地测试向量：`make provider-conformance-check`。 - 手动提供商验证元数据：`make provider-proof-check`。 - 完整的仓库门禁：`make finalize`。 - 脱敏的生产环境预检： `WEBHOOKERY_ENVIRONMENT=production go run ./cmd/whcp doctor production`。 - 脱敏的试点预检： `go run ./cmd/whcp doctor pilot --no-network`。 - 一次性实时数据库门禁： `WEBHOOKERY_TEST_DATABASE_URL=postgres://... make live-postgres-check`。 - 发行候选验收： `WEBHOOKERY_TEST_DATABASE_URL=postgres://... make rc-check`。 - Postman 和 Bruno 冒烟测试集合：参见 `collections/`。 ## 生产环境 RC 就绪状态 使用 `docs/operations.md`、`docs/day-2-operations.md`、`docs/stability.md` 和 `docs/release-evidence-template.md` 作为发行候选的 规范就绪路径。简短版本是：运行生产环境 doctor，`make finalize`，针对一次性数据库进行实时 PostgreSQL 检查，`make rc-check`，以及在涉及迁移或证据存储更改时进行恢复演练。 使用 `docs/observability.md` 获取入门的 Prometheus 规则和仪表板。切勿 将实时的提供商或客户凭据用于本地验收门禁。 试点发行详情位于 `docs/releases/v0.2.0-pilot.md`。发行 证据要求位于 `docs/release-evidence-template.md`，在 `docs/release-evidence-sample.md` 中有面向读者的示例，在 `docs/reference/release-evidence-index.md` 中有当前的公开 工件映射，在 `docs/production-rc-checklist.md` 中有简明的 运维人员检查清单。 ## 安全承诺与非声明 请参阅 `docs/security-promise.md` 了解规范的承诺和非声明。 简而言之：入站成功意味着持久化捕获和验证元数据已被 记录；这并不 意味着下游业务处理已成功。 本仓库中的示例使用占位符或本地开发值。切勿 将真实的 API 密钥、提供商凭据、webhook 密钥、bearer token、 私钥、原始签名、原始 payload 正文或客户数据放入文档、 提交、issue、支持请求或审计工件中。 商业许可例外、评估包、生产就绪 审查和支持包的边界在 `COMMERCIAL.md`、 `docs/commercial-evaluation.md`、`docs/production-readiness-review.md` 和 `docs/support-packages.md` 中进行了说明。 ## 主要文档 - `docs/index.md`：按受众、目的和 真实依据边界划分的规范文档映射。 - `docs/why-webhookery.md`：产品切入点以及契合/不契合场景的解释。 - `docs/configuration.md`：规范的环境变量和密钥处理 参考。 - `docs/reference/source-of-truth.md`：针对发行、 API、工作流、部署和文档工件的公开真实依据映射。 - `docs/reference/openapi.md`：渲染的 OpenAPI 和 API 契约矩阵 参考。 - `docs/reference/api-contract-matrix.md`：从 `openapi.yaml` 生成的操作矩阵。 - `docs/reference/release-evidence-index.md`：公开发行的工件映射和 验证说明。 - `docs/reference/release-validation.md`：发行验证和证据 工作流。 - `docs/evaluator-quickstart.md`：本地引导评估者演练。 - `examples/webhook-evidence-demo/`：确定性的本地虚假 provider 和 虚假接收方证据演示。 - `site/index.html`：静态产品落地页。 - `docs/operations.md`：运维手册和生产环境 RC 流程。 - `docs/failure-drills.md`：本地和试点故障演练计划、脚本使用， 以及恢复演练证据规则。 - `docs/feature-behavior.md`：捕获、路由、 交付、重放、对账、保留、身份、生产者信任和 SSRF 的行为参考。 - `docs/security-promise.md`：规范的持久化捕获承诺和 非声明。 - `docs/error-codes.md`：稳定的 API/CLI 错误代码参考。 - `docs/stability.md`：兼容性、支持窗口、迁移和 弃用策略。 - `docs/performance-envelope.md`：性能冒烟测试使用、容量输入、 存储增长和规模调整注意事项。 - `docs/documentation-maintenance.md`：提供商新鲜度和文档 审查清单。 - `docs/provider-conformance.md`：提供商矩阵、本地向量证据，以及 指向手动实时提供商验证指南的链接。 - `docs/providers/stripe.md` 和 `docs/providers/github.md`：首批 旗舰提供商的运维指南。 - `docs/providers/shopify.md`：首个电子商务 后续提供商的运维指南。 - `docs/live-provider-proof/stripe.md` 和 `docs/live-provider-proof/github.md`：手动脱敏验证指南。 - `docs/live-provider-proof/shopify.md`：手动脱敏的 Shopify 验证指南。 - `docs/deployment.md`：常见的自托管部署姿态。 - `docs/pilot-topology.md`：针对初始试点的有限支持拓扑。 - `docs/pilot-evidence-template.md`：脱敏的试点证据包模板。 - `docs/evidence-bundle-profiles.md`：用于支持、 安全审查、商业评估和内部取证的安全包配置策略。 - `docs/use-cases/stripe-payment-investigation.md`、 `docs/use-cases/github-automation-webhooks.md`、 `docs/use-cases/shopify-order-webhooks.md` 和 `docs/use-cases/internal-integration-replay.md`：与 事件包相关联的情景导向评估工作流。 - `docs/schema-migrations.md`：schema 审查、迁移排序和恢复 兼容性指南。 - `docs/security-review-package.md`：安全审查员工件映射。 - `docs/external-review-package.md`：外部审查包索引。 - `docs/release-evidence-template.md`：规范发行证据模板。 - `docs/production-rc-checklist.md`：发行候选就绪检查清单。 - `docs/releases/v0.2.0-pilot.md`：试点预发行说明。 - `docs/releases/v0.1.0-rc1.md`：首个发行候选说明。 - `docs/demo-media-checklist.md`：安全截图/视频检查清单。 - `docs/customer-discovery-notes-template.md`、 `docs/pilot-feedback-template.md`、`docs/roadmap-intake-policy.md` 和 `docs/pilot-review-checklist.md`：评估者和试点反馈规范。 - `.github/ISSUE_TEMPLATE/evaluator-feedback.yml`：公开的脱敏反馈 issue 表单。 - `docs/commercial-evaluation.md`、`docs/production-readiness-review.md` 和 `docs/support-packages.md`：商业评估和支持边界。 - `docs/cli.md`：CLI 命令参考和已移动的命令目录。 - `sdk/README.md`：已提交的 SDK 工件指南。 - `collections/README.md`：Postman 和 Bruno 冒烟测试请求使用说明。 - `deploy/kubernetes/README.md`、`deploy/helm/webhookery/README.md` 和 `deploy/terraform/webhookery-helm/README.md`：部署配置说明。 - `SECURITY.md`、`CONTRIBUTING.md`、`GOVERNANCE.md`、`SUPPORT.md`、 `CODE_OF_CONDUCT.md`、`CODEOWNERS`、`COMMERCIAL.md` 和 `TRADEMARKS.md`： 项目政策文档。 运行make help` 获取项目自有的命令列表。保持 README 示例简短； 将详细的命令工作流放入相关的规范文档中。

标签：EVTX分析, Go语言, OpenAPI, Webhook, 力导向图, 子域名突变, 审计日志, 日志审计, 测试用例, 消息队列, 程序破解, 自托管, 请求拦截