Webhook AsyncAPI Specification Drafting Prompt

This prompt is designed for API designers and platform engineers who already have a catalog of webhook events—including their names, trigger conditions, payload structures, and delivery channel information—and need to convert that knowledge into a machine-readable AsyncAPI 2.x specification. The job-to-be-done is structuring existing event knowledge into a standards-compliant contract that downstream tools like AsyncAPI Generator, EventCatalog, or Bump.sh can consume directly. You should use this prompt when you have defined event types and payload schemas but need them formatted as a valid AsyncAPI document with proper channels, message definitions, security schemes, and server bindings. The prompt assumes you bring the domain knowledge; it does not invent event schemas or design your event architecture from scratch.

Do not use this prompt for generating OpenAPI or Swagger REST endpoint documentation—AsyncAPI and OpenAPI serve different architectural patterns and the prompt is optimized for event-driven contracts only. Do not use it when you have not yet specified your event payloads or when you need prose-heavy integration guides or tutorials for consumers. The output is a YAML or JSON specification file, not a narrative document. If you are still designing your event schema, use the Webhook Payload Schema Generation Prompt first to define your payloads, then return to this prompt to assemble the full AsyncAPI specification. For consumer-facing documentation like quickstart guides or troubleshooting references, use the dedicated webhook documentation prompts in this pillar instead.

Before running this prompt, gather your event catalog with at minimum: event type names, descriptions, trigger conditions, JSON Schema definitions for each payload, the channel or topic each event publishes to, your server or broker connection details, and any security requirements like API keys or OAuth2 flows. The prompt works best when you provide structured input—a table or structured object of events—rather than freeform notes. After generating the specification, validate it against the AsyncAPI 2.x JSON Schema to catch structural errors, then test it with your target toolchain to confirm compatibility. For high-stakes specifications that govern production contracts, always include a human review step to verify that the generated channels, message schemas, and security schemes match your actual infrastructure before publishing.

The prompt below is designed to be pasted directly into your AI system. It forces the model to act as an API specification generator, consuming a structured event catalog and producing a standards-compliant AsyncAPI document. All configuration points are exposed as square-bracket placeholders, which you must replace with your actual data before execution. The prompt explicitly instructs the model to output only the YAML specification with no surrounding commentary, making the output safe for direct piping into validation tools or code generators.

yamlCopy
You are an API specification generator. Your only task is to produce a valid AsyncAPI 2.6.0 YAML document from the provided event catalog.

# INPUTS
- Event Catalog: [EVENT_CATALOG_JSON]
- API Title: [API_TITLE]
- API Version: [API_VERSION]
- Server Description: [SERVER_DESCRIPTION]
- Server URL: [SERVER_URL]
- Server Protocol: [SERVER_PROTOCOL]

# CONSTRAINTS
- Output ONLY the raw AsyncAPI YAML. Do not include any markdown fences, introductory text, or explanatory notes.
- Every event in the catalog must map to a channel with a publish operation.
- Use the event name as the channel address, prefixed with a forward slash (e.g., `/user.created`).
- Generate a JSON Schema for each event's payload from the provided [EVENT_CATALOG_JSON]. Include at least one example in each schema.
- Include a `securitySchemes` section if [SECURITY_SCHEME_TYPE] is provided. Supported types: `userPassword`, `apiKey`, `bearer`, `oauth2`.
- Bind the server to the [SERVER_PROTOCOL] and include a `ws` binding if the protocol is `ws`.
- The `info` object must include the title, version, and a description that mentions the number of documented events.
- Use `asyncapi: 2.6.0`.

# OUTPUT FORMAT
asyncapi: 2.6.0
info:
  title: [API_TITLE]
  version: [API_VERSION]
  description: "..."
servers:
  production:
    url: [SERVER_URL]
    protocol: [SERVER_PROTOCOL]
    description: [SERVER_DESCRIPTION]
channels:
  [EVENT_CHANNEL_1]:
    publish:
      message:
        payload:
          type: object
          properties: ...

To adapt this template, replace each bracketed placeholder with your concrete data. [EVENT_CATALOG_JSON] should be a structured JSON object where keys are event names and values are objects describing the payload fields, types, and descriptions. If your system does not require security, remove the securitySchemes instruction and the corresponding placeholder. For production use, always pipe the model's raw output through an AsyncAPI validator (like the official asyncapi CLI tool) before accepting it. A common failure mode is the model wrapping the YAML in a markdown code fence despite the constraint; a simple post-processing step to strip leading and trailing fences will harden your pipeline.

To integrate this prompt into a production pipeline, call the LLM API with the fully rendered prompt string. Set response_format to { "type": "json_object" } if your provider supports structured output modes, and instruct the model to return the AsyncAPI specification inside a JSON wrapper such as {"asyncapi_spec": "<YAML string>"}. This simplifies parsing and reduces the risk of extracting the YAML from free-text responses. After receiving the response, extract the YAML string from the JSON payload and write it to a .yaml file for validation.

Validation is the critical gate before any spec is published or consumed by downstream tools. Run the generated YAML through the official AsyncAPI parser CLI (asyncapi validate spec.yaml) or the @asyncapi/parser JavaScript library. If validation fails, capture the specific error messages—including line numbers, schema violations, and missing required fields—and feed them back into a repair prompt. The repair prompt should include the original generation context, the invalid spec, and the exact validation errors, instructing the model to produce a corrected version that resolves each error without introducing new ones. Log every generation attempt, the validation result, and the final spec version for auditability.

For production pipelines, store the validated spec in a git repository and trigger downstream documentation generation tools (such as AsyncAPI React renderer or custom doc site builds) on merge to the main branch. Never publish an unvalidated spec. Even if the spec passes structural validation, inspect it for placeholder payload examples (e.g., "string", 12345, or obviously hallucinated data) and flag any suspicious content for human review before publication. Consider adding a second evaluation step that checks for semantic completeness: do all channels have descriptions, do all messages have examples, and are security schemes fully defined? This catches gaps that schema validation alone will miss.