Webhook Rejection Response Documentation Prompt

This prompt is for integration engineers and platform teams who need to produce a precise, machine-actionable specification for how a webhook consumer must signal rejection of an event. The core job-to-be-done is not to document the happy path, but to define the contract for failure: the exact HTTP status codes, the required error body schema, and the operational consequences that follow each type of rejection. Use this when you are building a webhook provider and must tell your consumers, unambiguously, 'If you reject an event for reason X, respond with Y, and expect Z to happen next.' The output should be rigorous enough that a consumer's engineering team can implement their rejection handler without guessing, and your own support and SRE teams can interpret rejection signals consistently.

The ideal user is a technical writer or platform engineer who already has the event catalog, payload schemas, and delivery guarantee documentation defined. This prompt assumes you know what events you send and what constitutes a valid payload. It focuses narrowly on the rejection interface. Required context includes: the list of event types, the expected consumer acknowledgment window, the retry policy, and the distinction between transient errors (which trigger retries) and permanent rejections (which route to a dead-letter queue or alerting system). Do not use this prompt if you haven't yet defined your delivery semantics or retry behavior; the rejection specification must be consistent with those upstream decisions, and using this prompt without them will produce contradictory documentation.

The prompt template below is designed to be adapted with your specific event types, status code conventions, and operational workflows. Before using it, gather your existing webhook documentation artifacts—payload schemas, retry policy, dead-letter queue design, and alerting runbooks. The prompt forces you to distinguish between at least three rejection categories: silent drops (the event is discarded without alerting), retryable errors (the provider will retry with backoff), and alert-worthy failures (the event is dead-lettered and an on-call notification fires). If your system only has one or two of these categories, adapt the [REJECTION_CATEGORIES] placeholder accordingly, but be explicit about the gap. After generating the specification, validate it against your retry policy documentation to ensure no contradictions—for example, a 500 response classified as a 'silent drop' while your retry policy states all 5xx responses are retried. Human review is required before publishing this specification to external consumers, as misclassification of rejection responses can cause data loss, duplicate processing, or missed alerts.

This prompt template is designed to produce a complete specification for webhook rejection responses. It guides the model to define the exact HTTP status codes, error body schemas, and operational consequences of a rejection. The output is intended to be a section of your webhook documentation that leaves no ambiguity for the integrating developer. Copy the block below directly into your AI harness, replacing the square-bracket placeholders with your specific event contract details.

markdownCopy
You are an expert integration engineer writing a section of a webhook documentation page. Your task is to define the exact protocol for a consumer to reject a malformed, unexpected, or unprocessable webhook event.

Use the following inputs to generate the documentation:
- Event Type: [EVENT_TYPE_NAME]
- Delivery Semantics: [DELIVERY_GUARANTEE]
- Retry Policy Summary: [RETRY_POLICY_SUMMARY]
- Idempotency Key Location: [IDEMPOTENCY_KEY_HEADER_OR_FIELD]
- Alerting Threshold: [ALERTING_THRESHOLD]

Generate a documentation section titled "Rejecting an Event" that includes the following subsections:
1.  **Expected Response Codes**: A table mapping HTTP status codes (e.g., 400, 422, 500) to their specific meaning in the context of this webhook. Explicitly state that a 2xx status code signifies successful processing and will stop retries.
2.  **Error Response Body Schema**: A strict JSON Schema definition for the response body a consumer must return on rejection. The schema must include fields for `error_code` (a machine-readable string), `message` (a human-readable explanation), and `rejection_cause` (an enum of [REJECTION_CAUSES]).
3.  **Rejection Consequences**: A clear explanation of what happens on our side after a rejection. This must cover:
    - How it interacts with the retry policy: [RETRY_POLICY_SUMMARY].
    - Whether a rejection triggers an immediate alert or is aggregated: [ALERTING_THRESHOLD].
    - The effect on the idempotency key state: [IDEMPOTENCY_KEY_HEADER_OR_FIELD].
4.  **Consumer Implementation Guidance**: A concise checklist for the consumer developer. This must include a warning not to send a 2xx status code for events they cannot process, as this will permanently drop the event without alerting.

[CONSTRAINTS]:
- Do not invent HTTP status codes. Use only standard codes.
- The JSON Schema must be valid and strictly typed.
- The language must be direct and instructional, suitable for an external API reference.
- If the retry policy includes a dead-letter queue, mention it in the consequences section.

To adapt this template, replace the placeholders with your system's specific parameters. For example, [REJECTION_CAUSES] might be ["INVALID_PAYLOAD", "UNSUPPORTED_EVENT_TYPE", "DUPLICATE_EVENT"]. The [CONSTRAINTS] section is critical for high-risk workflows; you should add or modify constraints to enforce your internal documentation standards, such as requiring a specific tone or forbidding passive voice. After generating the documentation, always validate the JSON Schema with a standard library to ensure it is syntactically correct before publishing.

This prompt is designed to be called programmatically as part of a documentation generation pipeline, not as a one-off chat interaction. The typical integration point is a CI/CD step that runs after webhook event schemas or consumer contracts are updated. When a new event type is added or an existing payload changes, the harness should extract the event name, expected schema, and any known rejection conditions from the source of truth (an OpenAPI spec, an AsyncAPI document, or an internal event registry) and pass them into the prompt as [EVENT_TYPE], [PAYLOAD_SCHEMA], and [REJECTION_CONDITIONS]. The output—a structured rejection specification—should be validated against a predefined JSON Schema before it is merged into the public-facing webhook documentation site.

Validation is the first critical harness layer. The prompt's [OUTPUT_SCHEMA] placeholder should be populated with a strict JSON Schema that requires fields such as http_status_code, error_body_structure, rejection_reasons, alert_trigger, and consumer_action. After the model responds, run the output through a schema validator. If validation fails, retry once with the validation errors appended to [CONSTRAINTS]. If the second attempt also fails, log the failure, flag the event type for manual review, and block the documentation publish. For high-volume pipelines, consider using a cheaper model for the first attempt and escalating to a more capable model only on validation failure. This keeps costs predictable while maintaining quality.

The harness must also enforce consistency with sibling documentation. After generating a rejection specification, compare the http_status_code and retry guidance against the existing retry policy and acknowledgment protocol docs for that event family. A simple post-generation check can flag contradictions—for example, if the rejection spec says 'return 400 to stop retries' but the retry policy says 'all non-2xx responses trigger retries.' These cross-reference checks should be implemented as deterministic rules in the harness, not as additional LLM calls. When a conflict is detected, surface it to the documentation team with both sources cited rather than silently overwriting one.

Human review remains essential for any rejection specification that introduces a new error code, changes alerting behavior, or modifies the consumer contract. The harness should tag outputs with a review_required boolean based on simple heuristics: is this a new event type? Does the rejection spec include a 5xx status? Does it trigger a pager alert? If any condition is true, route the output to a review queue before publication. For established event types where only minor wording changes occur, automated merge may be acceptable. Always log the full prompt, model response, validation results, and reviewer decision for auditability. This trace is invaluable when a consumer disputes a rejection behavior months later.