Webhook Versioning and Compatibility Prompt

This prompt is designed for API governance teams, platform architects, and technical leads responsible for managing the lifecycle of webhook event schemas. Its primary job is to produce a structured, actionable versioning and compatibility policy from a set of raw inputs, such as an existing event catalog, a changelog of intended modifications, or a plain-text description of a proposed breaking change. The ideal user is someone who needs to transform an engineering decision ('we're adding a new required field to the order.shipped event') into a formal, consumer-facing document that defines the new version, specifies the deprecation timeline, and provides a clear migration path. This is not a prompt for generating initial event schemas or for one-off payload examples; it is specifically for governing the evolution of schemas that are already in production.

To use this prompt effectively, you must provide concrete context. The required [CURRENT_SCHEMA] and [PROPOSED_CHANGES] placeholders demand precise input, such as a JSON Schema diff, an OpenAPI fragment, or a detailed list of field additions, removals, or type modifications. The prompt's value is in its ability to detect and classify breaking changes against a set of predefined [COMPATIBILITY_RULES], and then generate a policy that includes a version bump rationale, a deprecation window, and consumer migration steps. The output is not just a policy document; it's a structured artifact that can be parsed by a downstream CI/CD pipeline to enforce compatibility gates. For example, if a change is classified as non-breaking, the prompt can generate a compatibility statement that is automatically attached to a pull request, preventing a manual review bottleneck.

Do not use this prompt for initial API design, for documenting static webhook payloads, or for generating marketing-facing changelogs. It is ill-suited for scenarios where the change is purely additive and non-breaking, as the overhead of a full versioning policy may be unnecessary. Furthermore, this prompt is a decision-support tool, not an automated enforcer. Its output must be reviewed by a human who owns the API contract before publication. The generated policy should be treated as a high-quality draft that requires validation against real consumer impact, internal service-level objectives (SLOs), and the practical limits of your deprecation tooling. The next step after generating the policy is to run it through an evaluation harness that checks for internal consistency, such as ensuring the deprecation date is not in the past and that all removed fields have a documented replacement.

The following prompt template is designed to produce a structured versioning and compatibility policy for webhook event schemas. It forces the model to define explicit rules for what constitutes a breaking change, how deprecation is communicated, and what migration path consumers must follow. Use this template when you need a consistent, reviewable policy document that can be shared across API governance, platform engineering, and integration teams.

textCopy
You are an API governance specialist documenting webhook event schema evolution for [PLATFORM_NAME].

Your task is to produce a versioning and compatibility policy that covers:
- How event schema versions are numbered and incremented.
- What changes are considered backward-compatible versus breaking.
- The deprecation timeline, including announcement windows and removal dates.
- The exact steps consumers must take to migrate between versions.
- How the platform communicates breaking changes to subscribed consumers.

Use the following inputs to ground your policy:
[CURRENT_EVENT_CATALOG]
[PROPOSED_SCHEMA_CHANGES]
[EXISTING_VERSIONING_POLICY]
[CONSUMER_IMPACT_ASSESSMENT]

Your output must conform to this schema:
[OUTPUT_SCHEMA]

Apply these constraints:
[CONSTRAINTS]

If any proposed change is ambiguous or cannot be classified as compatible or breaking with the available information, flag it explicitly and request clarification rather than guessing.

Before finalizing, run the following self-check:
1. Does every breaking change have a corresponding migration step?
2. Are deprecation dates concrete and in the future?
3. Is the consumer communication plan specific about channels and timing?
4. Are there any claims of backward-compatibility that the schema changes contradict?

Adaptation guidance: Replace each square-bracket placeholder with concrete inputs before sending this prompt to a model. [OUTPUT_SCHEMA] should be a strict JSON Schema or structured format definition so you can validate the response programmatically. [CONSTRAINTS] should include rules like "never remove a required field without a major version bump" or "deprecation windows must be at least 90 days." If you are working in a regulated domain, add a constraint requiring human review before the policy is published. For high-risk workflows, pipe the model's output through a validation step that checks for missing migration steps, ambiguous compatibility claims, and inconsistent timelines before the document reaches a consumer.

This prompt is designed to be called programmatically as part of an API governance pipeline, not as a one-off chat interaction. The typical integration point is a CI/CD check that runs when an OpenAPI or AsyncAPI specification changes, or when a platform team drafts a new event schema. The prompt expects a structured [INPUT] containing the current event schema, the proposed change, and the existing versioning policy. The output should be treated as a draft policy artifact that requires human review before publication to consumers.

Wire the prompt into a lightweight service or GitHub Action that constructs the input payload from your spec repository and policy documents. The [INPUT] should include: the full JSON Schema or AsyncAPI definition of the current event, the proposed new schema, the existing versioning policy document (if any), and a [CONSTRAINTS] block specifying your organization's compatibility rules (e.g., 'field additions are non-breaking, field removals require a major version'). After the model returns the draft versioning assessment, run a structured validation step: parse the output for required sections (breaking change classification, consumer migration steps, deprecation timeline), check that every claimed breaking change maps to a concrete schema diff, and flag any backward-compatibility claim that lacks evidence from the input schemas. Use a deterministic diff tool (like openapi-diff or json-schema-diff) to verify the model's breaking change detection against ground truth before accepting the output.

For high-stakes APIs where a missed breaking change could break paying customers, implement a mandatory human review gate. The prompt output should be rendered in a review interface that highlights claimed breaking changes alongside the raw schema diff, so reviewers can quickly validate or reject each claim. Log every prompt invocation with the input schemas, model version, output, and reviewer decision. This audit trail is essential for governance teams that need to demonstrate versioning diligence to compliance or security reviewers. Avoid using this prompt as an automated approval step without human oversight—schema evolution decisions carry operational risk that warrants human judgment, especially for additive changes that might still break consumers in subtle ways (e.g., adding a required field, changing enum values, or tightening validation constraints).