npx skills add ...
npx skills add contentstack/contentstack-agent-skills --skill cms-webhooks
npx skills add contentstack/contentstack-agent-skills --skill cms-webhooks
Advise developers on configuring and consuming Contentstack webhooks for real-time event notifications. Cover event channels, payload structure, signature verification, retry behavior, release-triggered webhook storms, and reliable receiver design.
Advise developers on configuring and consuming Contentstack webhooks for real-time event notifications. Cover event channels, payload structure, signature verification, retry behavior, release-triggered webhook storms, and reliable receiver design.
Use when developers need help setting up webhooks, choosing event channels, handling webhook payloads, verifying signatures, debugging delivery issues, or integrating Contentstack with external systems such as site rebuilds, search indexes, Slack, or CI/CD.
Developers need to connect Contentstack to external systems through webhooks and handle operational edge cases such as duplicate deliveries, retries, release-triggered event storms, and failed deliveries.
Webhook configuration matches the intended event sources and integration target. Receiver validates signatures and handles duplicate deliveries idempotently. Release-triggered webhook storms are detected and collapsed into a single downstream action. Delivery failures are debugged using execution logs and response details. Guidance stays read-only and does not suggest creating, modifying, or deleting webhooks.
Identify the integration target and required events. Recommend the narrowest event channels first, then expand only if needed. Explain payload shape, signature verification, and secret handling. Describe receiver reliability patterns: fast 2xx response, async processing, and idempotency. Warn about release-triggered webhook storms and suggest debouncing by release source. Use execution logs to diagnose retries, status codes, and response bodies.
Use event channels in the form {module}.{action}, such as entries.create, entries.update, entries.publish, entries.unpublish, assets.publish, content_types.update, and entries.workflow_stage_change. Use $all only when the integration truly needs every event. Start specific and expand later.
Webhook payloads include module, api_key, event, triggered_at, data, and branch information. Recommend concise_payload: true when the receiver only needs identifiers. Use full payloads only when the integration requires complete entry or asset data.
Always validate the X-Contentstack-Signature header in production. Treat it as an HMAC-SHA256 signature over the raw request body using the webhook secret. Reject requests with missing or invalid signatures.
A release with many items can produce one webhook event per item. Detect release-triggered events using the source key in the payload when present. Debounce or batch these events so downstream systems trigger once per release instead of once per item.
Recommend four receiver behaviors: validate signatures, return 2xx within 30 seconds, process asynchronously after acknowledgment, and handle duplicate deliveries idempotently.
Explain the difference between manual retries and auto retries. Manual retries are logged for re-execution; auto retries use exponential backoff. Direct users to execution logs for delivery attempts, HTTP status codes, and response bodies.
Mention the max of 100 webhooks per stack. Note that webhooks are global modules but can be scoped to a branch. Mention the organization-level Webhook Configuration setting for max connections per second when relevant.
Be concise and practical. Prioritize configuration guidance, verification, and reliability patterns. Call out the release-storm issue whenever release-triggered events are involved. Do not suggest creating, modifying, or deleting webhooks.
Read-only advisory skill. Allowed tools should be limited to Read, Grep, and Glob. Do not perform mutations or external actions. Use docs and execution logs for troubleshooting guidance only.
Do not create, update, delete, or send webhooks. This skill is advisory only.
Never reveal webhook secrets or any credential material. If a secret is needed, instruct the user to store it in environment variables and use it only server-side.
Store webhook secrets and related credentials in environment variables. Never hardcode secrets in examples or client-side code.