Webhook vs Polling Decision Prompt for Documentation

This prompt is designed for integration architects, platform engineers, and technical writers who need to produce a clear, unbiased decision framework for their API consumers. The framework compares webhooks and polling across dimensions like latency, reliability, infrastructure complexity, and cost. Use this prompt when you are writing developer documentation that must guide a reader toward the right integration pattern for their specific use case, without pushing a single solution. The output is a structured comparison that can be embedded directly into a developer portal or integration guide.

The ideal user has access to the internal specifications for both the webhook delivery system and the polling endpoints, including concrete numbers for rate limits, typical payload sizes, delivery latency percentiles, and retry behavior. Without this context, the model will produce a generic comparison that lacks the specificity needed for a real integration decision. You should provide [CONTEXT] with exact latency SLOs, infrastructure requirements for both sides, and any known failure modes. The prompt works best when you also supply [CONSTRAINTS] that define the audience's technical level and the documentation's tone requirements.

Do not use this prompt when you are writing marketing copy that favors one pattern, when the decision has already been made by your platform team, or when you lack concrete data about your system's behavior. A decision framework built on assumptions rather than measurements will mislead consumers and generate support tickets. If your platform only supports webhooks, write a webhook quickstart instead. If you are documenting a third-party API without access to their infrastructure details, limit the output to a feature comparison table and avoid making reliability claims you cannot verify. For high-stakes integration decisions where the wrong pattern could cause data loss, always route the final output through a human review step with an engineer who understands the production behavior of both paths.

The following prompt template is designed to be pasted directly into your AI system. It instructs the model to act as an integration architect and produce a balanced, evidence-based comparison between webhook and polling patterns. The output is a decision framework tailored to a specific platform, not a generic list of pros and cons. Replace every placeholder in square brackets with your platform's concrete details before execution. The more specific you are about your system's actual behavior, the more useful and accurate the generated documentation will be for your consumers.

codeCopy
You are a senior integration architect writing a decision guide for developers who need to consume events from [PLATFORM_NAME]. Your goal is to help them choose between webhooks and polling based on [PLATFORM_NAME]'s specific capabilities and constraints.

## Platform Context
- Webhook delivery model: [WEBHOOK_DELIVERY_MODEL, e.g., at-least-once with exponential backoff retry for 24 hours]
- Webhook ordering guarantees: [ORDERING_GUARANTEES, e.g., no ordering guarantees; events may arrive out of order]
- Webhook payload format: [PAYLOAD_FORMAT, e.g., JSON with a standard envelope containing event_id, event_type, timestamp, and data]
- Polling API endpoint: [POLLING_ENDPOINT, e.g., GET /v1/events with cursor-based pagination]
- Polling rate limits: [RATE_LIMITS, e.g., 100 requests per minute per API key]
- Polling data retention: [RETENTION_PERIOD, e.g., events are queryable for 7 days]
- Signature verification: [SIGNATURE_METHOD, e.g., HMAC-SHA256 with a shared secret]
- Idempotency support: [IDEMPOTENCY_DETAILS, e.g., idempotency key is the event_id; replay events within 72 hours]

## Output Schema
Generate a decision framework document with the following sections. Use markdown.

### 1. Quick Decision Summary
A 3-4 sentence summary that helps a developer make a fast choice. State the primary reason to choose webhooks and the primary reason to choose polling for [PLATFORM_NAME].

### 2. Comparison Table
A markdown table comparing webhooks and polling across these dimensions:
- Latency
- Reliability and delivery guarantees
- Infrastructure complexity for the consumer
- Data freshness
- Error handling burden
- Security requirements
- Cost to the consumer
- Ordering guarantees
- Replay and recovery capability

### 3. When to Use Webhooks
Describe 3-4 concrete scenarios where webhooks are the better choice for [PLATFORM_NAME] consumers. Reference the platform's specific webhook behavior.

### 4. When to Use Polling
Describe 3-4 concrete scenarios where polling is the better choice for [PLATFORM_NAME] consumers. Reference the platform's specific polling API behavior.

### 5. Hybrid Approach
Describe a practical hybrid pattern that combines webhooks for notification and polling for state reconciliation. Include a code-agnostic sequence diagram in text.

### 6. Common Pitfalls
List 3-5 common mistakes consumers make when choosing or implementing either pattern against [PLATFORM_NAME], with specific mitigation advice.

## Constraints
- Do not invent platform capabilities not described in the Platform Context.
- If a dimension in the comparison table cannot be answered from the provided context, mark it as "Platform-specific; see docs."
- Present both patterns fairly. Do not steer the reader toward one pattern unless the platform context makes one pattern objectively unsuitable.
- Use precise language about delivery guarantees. Never claim exactly-once delivery unless the Platform Context explicitly states it.
- Include a note that consumers should verify their own infrastructure's ability to handle webhook traffic or polling volume.

After pasting this template, replace each bracketed placeholder with data from your actual system. If your platform does not support a feature mentioned in a placeholder—for example, if you have no idempotency mechanism—replace the value with an honest statement like "No idempotency support; consumers must deduplicate using event_id." Do not leave placeholders unresolved. The model will use whatever you provide, so inaccurate context will produce inaccurate documentation. Test the output against your platform's real behavior before publishing. For high-stakes integration documentation, route the generated content through a technical review step where an engineer confirms every claim about delivery guarantees, rate limits, and failure modes.

This prompt is designed to be called programmatically as part of a documentation authoring pipeline, not as a one-off chat interaction. The primary integration point is a documentation service that receives an API product context and a target audience, then returns a structured decision framework. The harness should treat the prompt as a stateless function: it takes a structured [CONTEXT] object and returns a [DECISION_FRAMEWORK] JSON object. Do not maintain conversation history across calls; each invocation should be self-contained with all necessary context provided in the input.

Input Assembly: Construct the [CONTEXT] object by merging data from your API gateway, product spec, and existing documentation. Required fields include api_name, api_type (e.g., 'async', 'sync', 'hybrid'), current_support (list of supported patterns: 'webhook', 'polling', 'websocket'), latency_profile (e.g., 'near-real-time', 'batch'), payload_size_range, authentication_methods, and consumer_profiles (an array of objects with role, infrastructure_capabilities, and latency_tolerance). Model Choice: Use a model with strong JSON mode and structured output support (e.g., gpt-4o, claude-3-opus). Set response_format to json_schema and provide the expected [OUTPUT_SCHEMA] as a strict JSON Schema definition. Validation: Before returning the output to the documentation pipeline, validate the JSON against the schema. Check that recommendation_matrix contains entries for every consumer profile provided in the input, that trade_off_summary includes at least latency, reliability, complexity, and cost dimensions, and that no recommendation is absolute (e.g., 'always use webhooks') without a conditional qualifier. If validation fails, retry once with the validation errors appended to the [CONSTRAINTS] field. If the second attempt fails, log the failure and route to a human reviewer queue.

Integration Points: Wire the prompt into your CI/CD pipeline for documentation updates. When an API version changes or a new consumer profile is added, trigger a re-generation of the decision framework. Store the output in your documentation CMS as a structured data object, not as raw markdown, so the frontend can render it as an interactive decision tool. Logging and Observability: Log the full prompt input, output, validation results, and any retries to your observability platform. Tag logs with prompt_id=webhook-vs-polling-decision, api_version, and consumer_profile_count for traceability. Human Review Gate: For any output where the trade_off_summary contains a confidence_score below 0.8 (as defined in your eval rubric), or where the recommendation_matrix suggests a pattern not currently supported by the API, flag the output for technical writer review before publication. Never auto-publish a decision framework that recommends an unimplemented pattern without explicit approval.