Webhook Migration Guide Prompt for Version Upgrades

This prompt is designed for platform teams that need to produce a precise, actionable migration guide when upgrading a webhook API from one version to another. The core job-to-be-done is converting a structured, machine-readable diff of event schema changes into a human-readable document that consumers can follow to update their integrations. The ideal user is an API product manager, a platform engineer, or a technical writer who has access to a formal schema diff—such as an OpenAPI or JSON Schema comparison—and needs to communicate breaking changes, deprecated fields, and new requirements without ambiguity. The prompt expects you to provide a complete inventory of what changed at the field level, not a high-level summary of new features.

You should only use this prompt when you have a concrete, structured diff that enumerates added, removed, renamed, or type-changed fields, along with any new validation constraints or required parameters. The prompt works best when the migration is purely a payload transformation problem: consumers must update their request or response handling code to match a new schema. It will generate a document with before/after payload comparisons, a catalog of breaking changes ranked by impact, step-by-step upgrade instructions, and a consumer readiness checklist. Do not use this prompt if the migration involves undocumented behavioral changes—such as altered rate limiting, new business logic side effects, or different idempotency semantics—that cannot be expressed as a schema diff. In those cases, the generated guide will be dangerously incomplete because the prompt cannot invent behavioral documentation from thin air.

Before using this prompt, ensure your schema diff is complete and validated. A partial diff will produce a migration guide with dangerous gaps that can break consumer integrations. After generating the guide, you must still review it for accuracy against the actual implementation, particularly for any implicit behavioral changes that the diff did not capture. The prompt is a drafting accelerator, not a replacement for human review of breaking changes that affect production integrations.

This prompt template is designed to be pasted directly into your AI workflow. It instructs the model to produce a structured migration guide for webhook consumers upgrading between event schema versions. The template uses square-bracket placeholders that you must replace with real values before execution. Each placeholder maps to a specific input source—such as your OpenAPI changelog, internal event catalog, or deprecation timeline—ensuring the generated guide is grounded in your actual API surface rather than hallucinated from general knowledge.

codeCopy
You are a technical documentation engineer for a platform team. Your task is to generate a webhook migration guide for consumers upgrading from event schema version [SOURCE_VERSION] to [TARGET_VERSION].

## REQUIRED INPUTS
- [CHANGELOG]: The full changelog or diff between the two versions, including all breaking changes, additive changes, and deprecations.
- [EVENT_CATALOG]: The complete event type catalog for both versions, with payload schemas for each event type.
- [DEPRECATION_TIMELINE]: Dates when deprecated fields, event types, or behaviors will be removed, and any sunset windows.
- [AUTH_CHANGES]: Any changes to signature verification, headers, or authentication requirements between versions.
- [RETRY_POLICY]: The current retry and delivery guarantee documentation for the target version.

## OUTPUT SCHEMA
Produce a migration guide in the following structure:
1. **Overview**: A 2-3 sentence summary of what changed and why consumers should upgrade.
2. **Breaking Changes Table**: A markdown table with columns: Event Type, Field/Behavior, Change Description, Before Example, After Example, Required Consumer Action.
3. **Deprecation Notices**: A list of deprecated fields, event types, or behaviors with their removal dates and recommended replacements.
4. **New Features**: A list of new event types, fields, or behaviors available in the target version.
5. **Upgrade Checklist**: An ordered list of steps a consumer must take to complete the migration, including testing and verification steps.
6. **Rollback Guidance**: Instructions for consumers who need to revert to the source version, including any data consistency risks.
7. **Timeline and Support**: Key dates for deprecation, end-of-life, and support contact information.

## CONSTRAINTS
- Every breaking change must include a before/after payload example.
- Do not invent event types, fields, or behaviors not present in [EVENT_CATALOG] or [CHANGELOG].
- If a deprecated field has no documented replacement, explicitly state "No replacement available" rather than guessing.
- All dates must be sourced from [DEPRECATION_TIMELINE]. If a date is not specified, use "TBD" and flag it for human review.
- The upgrade checklist must reference signature verification changes from [AUTH_CHANGES] if any exist.
- If [RETRY_POLICY] has changed, include a dedicated section on retry behavior migration.

## VALIDATION RULES
Before finalizing the output, verify:
- Every event type in [EVENT_CATALOG] for the target version is accounted for (no missing types).
- No breaking change is described without a corresponding entry in [CHANGELOG].
- All before/after examples conform to the schemas in [EVENT_CATALOG].
- The upgrade checklist is ordered by dependency (e.g., auth changes before payload changes).

## OUTPUT FORMAT
Return the migration guide as clean markdown suitable for publishing in a developer documentation portal.

To adapt this prompt for your environment, replace each placeholder with the actual content from your internal systems. The [CHANGELOG] should be a structured diff, not a free-text summary—this prevents the model from missing subtle breaking changes. The [EVENT_CATALOG] must include complete JSON Schema or OpenAPI-compatible payload definitions for both source and target versions. If your platform lacks a formal deprecation timeline, replace [DEPRECATION_TIMELINE] with a clear instruction like "No deprecation timeline exists; flag all deprecated fields for manual review." After generation, run the output through a schema validator to confirm that every before/after example in the breaking changes table conforms to the declared event schemas. For high-risk migrations affecting payment or compliance events, route the generated guide through a human documentation review step before publication.

This prompt is designed to be called programmatically as part of a release automation pipeline, not as a one-off chat interaction. When a platform team tags a new webhook version, a CI/CD job should assemble the required inputs—the old and new OpenAPI or AsyncAPI specs, a structured changelog of breaking changes, and the deprecated field mappings—and pass them into the prompt via the [OLD_SPEC], [NEW_SPEC], [BREAKING_CHANGES_LIST], and [DEPRECATED_FIELD_MAP] placeholders. The prompt expects these inputs as structured JSON or YAML strings, not free-text descriptions, so the harness must validate that each input parses correctly before invoking the model. If any input fails schema validation, the harness should abort early and log a clear error rather than sending malformed context to the model.

After the model returns a migration guide draft, the harness must run a post-generation validation suite before the guide reaches a human reviewer. At minimum, validate that every breaking change enumerated in the input appears in the output with a before/after payload comparison, that all deprecated fields listed in the input map are referenced in the guide, and that the output contains the required sections: breaking changes, additive changes, behavioral changes, and an upgrade checklist. Use a deterministic script to check for these structural requirements rather than relying on a second LLM call. For higher-risk migrations—those affecting authentication, payment events, or personally identifiable information—add a mandatory human approval step in the pipeline that blocks publication until a designated reviewer signs off. Log the prompt version, input hashes, model response, and validation results for auditability.

Choose a model with strong structured output capabilities and a context window large enough to hold both full specs plus the prompt. GPT-4o or Claude 3.5 Sonnet are reasonable defaults. Set temperature to 0 or a very low value (0.1) to maximize consistency across runs. If the generated guide fails structural validation, implement a single retry with the same inputs but append the validation errors to the prompt as [PREVIOUS_VALIDATION_ERRORS] so the model can self-correct. Do not retry more than once without human intervention—if the second attempt also fails, escalate to a human writer with the raw inputs and both failed outputs attached. Avoid wiring this prompt directly to a public-facing documentation site without the validation and approval gates described here.