Webhook Event Schema Validation Prompt

This prompt is for platform teams that need to automate the enforcement of event contracts. It generates documentation of schema validation rules, validation timing, and the consumer experience when validation fails. Use it when you need to produce clear, unambiguous documentation that distinguishes schema violations from business logic rejections. This is not a prompt for generating the schema itself. It assumes you already have a payload schema and need to document the validation behavior around it.

The ideal user is an integration engineer or API product manager who owns the webhook contract and needs to communicate validation expectations to consumers. You must provide the payload schema, the validation rules you intend to enforce, and the expected consumer response codes. The prompt works best when you have already decided on strict versus lenient validation, whether unknown fields are dropped or rejected, and what error bodies consumers will receive. Do not use this prompt if you are still designing the schema or if your validation logic is not yet implemented—the output will be speculative rather than descriptive.

Avoid using this prompt for documenting business logic rejections, such as 'order total exceeds credit limit' or 'event type not supported for this account.' Those are application-level decisions that happen after schema validation passes. The prompt is designed to isolate the contract enforcement layer: the shape, types, and required fields of the payload. If you need to document both schema validation and business logic rejection in a single page, run this prompt first, then layer in the business rules separately to maintain a clear separation of concerns.

This prompt template generates documentation that explains how your platform validates incoming webhook events against their declared schemas. It covers validation timing, the specific rules applied, and—critically—the consumer experience when validation fails. The output distinguishes between schema violations (malformed JSON, missing required fields, wrong types) and business logic rejections (invalid state transitions, authorization failures), which is essential for consumers debugging integration issues.

textCopy
You are a technical documentation engineer for a platform that sends webhooks.

Generate a documentation section titled "Event Schema Validation" for our webhook consumer docs.

Use the following inputs:
- [EVENT_CATALOG]: A list of event types and their JSON Schema definitions.
- [VALIDATION_POLICY]: Internal rules describing when validation occurs (e.g., on receipt, before processing, after enrichment) and how strict it is.
- [REJECTION_EXPERIENCE]: Details on what the consumer sees when validation fails (HTTP status codes, error body schema, logging, alerting).
- [CONSTRAINTS]: Specific documentation standards, tone, or sections to include or exclude.

Your output must follow this structure exactly:

## Schema Validation Overview
[2-3 sentences explaining the purpose and timing of validation in our pipeline.]

## Validation Rules by Event Type
For each event type in [EVENT_CATALOG], produce a subsection with:
- Event type name
- A table of validated fields with columns: Field Path, Type, Required, Additional Constraints
- A note on any conditional validation logic

## Schema Violation vs. Business Logic Rejection
A clear table distinguishing these two failure categories:
- Category: Schema Violation | Business Logic Rejection
- Trigger: [When it occurs]
- HTTP Status: [Status code]
- Error Body: [Link or example]
- Consumer Action: [What the consumer should do]

## Consumer Experience on Validation Failure
- The exact HTTP response body schema for validation errors
- An example error response
- How to distinguish validation errors from network errors, auth errors, and rate limiting
- Logging and monitoring guidance for consumers

## Testing Validation Behavior
- How to intentionally trigger a schema validation failure in our sandbox
- Example malformed payloads for common event types

[OUTPUT_SCHEMA]:
Return the documentation in Markdown. Use fenced JSON code blocks for all example payloads. Do not invent event types or fields not present in [EVENT_CATALOG].

[RISK_LEVEL]: HIGH. If [VALIDATION_POLICY] is ambiguous about timing or strictness, flag the ambiguity in a "Documentation Gaps" section at the end instead of guessing.

To adapt this template, replace each square-bracket placeholder with concrete data from your system. The [EVENT_CATALOG] should be a structured list of event names and their JSON Schema definitions—do not paste raw code without schema context. The [VALIDATION_POLICY] placeholder is critical: if your team has not formally defined when validation runs (e.g., at the API gateway versus in the event processor), you must resolve that ambiguity before generating docs, or the model will flag it as a gap. The [REJECTION_EXPERIENCE] input should include the exact HTTP status codes and error body schemas your platform returns, because consumers will code against these contracts. After generating the output, run a schema conformance check: every example payload in the documentation must validate against the JSON Schema provided in [EVENT_CATALOG]. For high-risk platforms processing financial or healthcare events, route the generated documentation through a human review step that verifies the distinction between schema violations and business logic rejections is unambiguous and matches the actual system behavior.

This prompt is designed to operate as a pre-commit or CI gate rather than a real-time validation engine. The ideal harness runs it whenever an event schema definition changes—typically in a pull request that modifies an OpenAPI, AsyncAPI, or JSON Schema file. The prompt receives the proposed schema plus the existing event catalog context and produces a structured validation report that your pipeline can parse and act on. Do not use this prompt at webhook delivery time; real-time payload validation belongs in your event gateway code, not in an LLM call.

Wire the prompt into a GitHub Action, GitLab CI job, or custom CLI tool that: (1) detects changed schema files in the PR, (2) loads the full event catalog as [CONTEXT], (3) passes each changed schema as [INPUT] with the [OUTPUT_SCHEMA] set to a strict JSON structure containing valid, errors[], warnings[], and consumer_impact fields, and (4) parses the model response. Validation layer: after receiving the LLM output, run a deterministic JSON Schema validator against the proposed schema itself. If the LLM claims validity but the deterministic validator finds structural errors, flag a model-vs-validator conflict for human review. Retry logic: if the model returns malformed JSON or fails to match [OUTPUT_SCHEMA], retry once with the error message appended as [CONSTRAINTS]. After two failures, fail the check and require manual review. Logging: capture the prompt version, model ID, input schema hash, output report, and any retry attempts as structured logs for auditability.

For model choice, prefer a model with strong JSON mode and schema-following capabilities (GPT-4o, Claude 3.5 Sonnet, or equivalent). Set temperature=0 to maximize consistency across runs. If your event catalog is large, use RAG-style context packing: embed the full catalog, retrieve the top-K most similar event types to the changed schema, and include only those in [CONTEXT] to stay within token limits while preserving relevant comparison surface. Human review gate: configure the pipeline to auto-merge only when valid is true and errors[] is empty. Any warnings[] or consumer_impact severity above low should trigger a PR comment with the full report and request a human reviewer's approval. This keeps schema enforcement automated without letting the model silently approve breaking changes.