mcpField
C
cms-webhooks

cms-webhooks

github.com/contentstack开发593 次安装2 周前更新
代码仓库

关于 cms-webhooks

面向 Contentstack 开发者的只读指导技能，涵盖 Webhook 配置、事件和载荷处理、签名验证及投递故障排查。重点说明重复投递、重试和发布事件风暴的可靠处理方式。

主要功能

  1. 01选择具体事件通道
  2. 02说明载荷与签名验证
  3. 03处理重复投递与重试
  4. 04预防发布事件风暴
  5. 05借助执行日志排查故障

适用场景

  1. 01配置内容发布后的站点重建通知
  2. 02验证请求是否来自 Contentstack
  3. 03排查发布时大量 Webhook 调用
  4. 04调查遗漏或失败的投递

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/contentstack/contentstack-agent-skills --skill cms-webhooks

安装后在 Claude Code 中输入/cms-webhooks确认已加载。

详细介绍

Contentstack Webhooks

描述

为开发者提供有关配置和使用 Contentstack Webhooks 以接收实时事件通知的建议。涵盖事件频道、负载结构、签名验证、重试行为、发布触发的 Webhook 风暴以及可靠的接收端设计。

适用场景

当开发者需要设置 Webhook、选择事件频道、处理 Webhook 负载、验证签名、调试投递问题，或将 Contentstack 与网站重建、搜索索引、Slack 或 CI/CD 等外部系统集成时使用。

用户问题

开发者需要通过 Webhook 将 Contentstack 连接到外部系统，并处理重复投递、重试、发布触发的事件风暴以及投递失败等运维边缘情况。

成功标准

Webhook 配置符合预期的事件来源和集成目标。 接收端验证签名，并以幂等方式处理重复投递。 检测并合并发布触发的 Webhook 风暴，使其只触发一次下游操作。 通过执行日志和响应详情排查投递失败。 指导内容仅限只读操作，不建议创建、修改或删除 Webhook。

预期输入

  • 集成目标（网站重建、搜索索引、Slack、CI/CD 等）
  • 所需事件类型
  • 可靠性和延迟要求
  • 负载详情或请求示例
  • 投递问题的调试信息

预期输出

  • Webhook 配置指导
  • 事件频道选择建议
  • 负载处理模式
  • 签名验证说明
  • 防止发布风暴的建议
  • 调试建议

用户请求示例

  • 如何在内容发布时触发网站重建？
  • 如何验证 Webhook 确实来自 Contentstack？
  • 部署发布内容时，我的 Webhook 接收端收到了数百次调用。
  • 应该使用什么重试策略？
  • 如何调试未成功投递的 Webhook？

工作流概述

确定集成目标和所需事件。 先推荐范围最窄的事件频道，仅在需要时再扩展。 说明负载结构、签名验证和密钥处理方式。 介绍接收端可靠性模式：快速返回 2xx、异步处理和幂等性。 提醒用户注意发布触发的 Webhook 风暴，并建议按发布来源进行防抖处理。 使用执行日志诊断重试、状态码和响应正文。

说明

频道

使用 {module}.{action} 格式的事件频道，例如 entries.create、entries.update、entries.publish、entries.unpublish、assets.publish、content_types.update 和 entries.workflow_stage_change。仅当集成确实需要所有事件时才使用 $all。先从具体频道开始，之后再扩展。

负载

Webhook 负载包含 module、api_key、event、triggered_at、data 和分支信息。如果接收端只需要标识符，建议使用 concise_payload: true。仅当集成需要完整的条目或资产数据时，才使用完整负载。

签名验证

在生产环境中，始终验证 X-Contentstack-Signature 标头。将其视为使用 Webhook 密钥对原始请求正文计算的 HMAC-SHA256 签名。拒绝缺少签名或签名无效的请求。

发布 Webhook 风暴

包含许多条目的发布可能会为每个条目生成一个 Webhook 事件。如果负载中存在 source 键，可据此识别由发布触发的事件。对这些事件进行防抖或批处理，让下游系统每次发布只触发一次，而不是每个条目都触发一次。

可靠的接收端设计

建议接收端遵循四项行为：验证签名、在 30 秒内返回 2xx、确认后异步处理，以及以幂等方式处理重复投递。

重试策略

说明手动重试与自动重试的区别。手动重试会记录下来以供重新执行；自动重试使用指数退避。引导用户查看执行日志，了解投递尝试、HTTP 状态码和响应正文。

限制和范围

提及每个堆栈最多可配置 100 个 Webhook。注意，Webhook 是全局模块，但可以限定到某个分支。相关时，提及组织级别的 Webhook Configuration 设置，用于配置每秒最大连接数。

输出格式

简洁实用。 优先提供配置指导、验证方法和可靠性模式。 涉及由发布触发的事件时，指出发布风暴问题。 不要建议创建、修改或删除 Webhook。

工具说明

只读咨询技能。 允许使用的工具仅限 Read、Grep 和 Glob。 不要执行变更或外部操作。 仅将文档和执行日志用于故障排查指导。

安全性

默认规则
  • 切勿暴露 Webhook 密钥。
  • 在生产环境中始终验证 X-Contentstack-Signature。
  • 所有密钥都使用环境变量。
  • 示例中不要回显原始密钥、令牌或签名。
  • 优先采用服务端验证和处理模式。
破坏性操作

不要创建、更新、删除或发送 Webhook。本技能仅提供咨询。

密钥

切勿泄露 Webhook 密钥或任何凭证材料。如果需要密钥，指导用户将其存储在环境变量中，并且仅在服务端使用。

环境变量

将 Webhook 密钥及相关凭证存储在环境变量中。示例或客户端代码中绝不硬编码密钥。

产品背景

    • 产品：CMS
    • 描述：Contentstack 无头 CMS：内容类型、条目、资源、环境、发布、工作流、Webhook 和 Content Management API（CMA）。
    • 产品安全规则：- 切勿暴露管理令牌或 API 密钥。
  • 凭证始终使用环境变量。
  • 在浏览器应用中，将所有 CMA 调用路由至服务端代理。
  • 切勿在客户端代码中硬编码堆栈 API 密钥。
    • 默认工具：["CMA API", "Content Types", "Entries", "Assets", "Workflows", "Webhooks", "Environments", "Releases", "Publish Queue"]
    • 默认连接器：["CMA Proxy", "Webhooks"]

评论

支持 Markdown