Webhook Ordering Semantics Explanation Prompt

This prompt is for platform and integration engineers who need to produce clear, accurate documentation explaining how their webhook system delivers events with respect to order. The core job is to translate internal delivery mechanics—such as partial ordering, causal ordering, sequence numbers, or the deliberate absence of ordering guarantees—into language that helps API consumers build correct integrations. The reader is a developer who must implement an event handler and needs to know whether they can rely on event A arriving before event B, or if they must design for out-of-order delivery and implement their own reordering logic.

Use this prompt when you are documenting a production webhook system and need to prevent integration bugs caused by incorrect assumptions about ordering. It is particularly valuable when your system provides nuanced guarantees, such as 'events for the same object ID are delivered in order, but events across different objects are not.' The prompt forces you to specify the scope of ordering (per-connection, per-object, per-event-type), the mechanism (sequence numbers, timestamps, vector clocks), and the consumer's responsibilities. It includes checks that flag misleading absolute-ordering claims like 'events are delivered in order' without qualification, which is almost never true in distributed systems.

Do not use this prompt if your webhook system has no ordering mechanism at all and you simply need to document at-least-once delivery with no sequence metadata. In that case, the Webhook Delivery Guarantee Documentation Prompt is a better fit. Also avoid this prompt if you are documenting a system that provides strict total ordering through a single-threaded event log—that architecture is rare, and the prompt's nuance around partial ordering will add unnecessary complexity. After generating the explanation, validate it against real delivery traces to ensure the documented behavior matches observed behavior, and have a second engineer review the text for accidental promises your system cannot keep.

This prompt template is designed to produce a developer-facing explanation of how your webhook system handles event ordering. It forces the model to distinguish between absolute ordering, partial ordering, causal ordering, and no ordering, and to surface the practical implications for consumers—such as the need for sequence numbers, timestamps, or client-side reordering buffers. Use this when you need to document ordering behavior for an event-driven API, and avoid it when your system has no ordering story at all (in which case, a simple disclaimer is more honest).

textCopy
You are a technical documentation engineer for a platform that sends webhooks. Your task is to write a clear, accurate section on event ordering semantics for our developer docs.

## Context
- Platform name: [PLATFORM_NAME]
- Event types covered: [EVENT_TYPE_LIST]
- Delivery mechanism: [DELIVERY_MECHANISM, e.g., HTTP POST, message queue]
- Ordering guarantee level: [ORDERING_LEVEL: none | partial | causal | total]
- If partial or causal: the ordering key is [ORDERING_KEY, e.g., entity_id, aggregate_id]
- Sequence metadata provided: [SEQUENCE_METADATA, e.g., X-Event-Sequence header, event.timestamp, event.sequence_number]
- Known limitations: [KNOWN_LIMITATIONS, e.g., "events for different entities may arrive out of order", "retries can produce duplicates that appear out of sequence"]

## Output Schema
Produce a markdown document with the following sections:
1. **Ordering Guarantee Statement**: A one-sentence summary of the guarantee.
2. **What This Means for Consumers**: Practical implications, including whether consumers must handle out-of-order delivery.
3. **Sequence Metadata**: How consumers can detect order using provided fields (timestamps, sequence numbers, etc.).
4. **Consumer-Side Reordering Strategies**: If ordering is not guaranteed, describe recommended approaches (e.g., buffer by timestamp, sort by sequence number, use a state machine).
5. **Edge Cases and Pitfalls**: Scenarios like clock skew, retries, partition changes, and concurrent events that can break ordering assumptions.
6. **Code Example**: A minimal consumer snippet in [LANGUAGE] that demonstrates safe event processing given these semantics.

## Constraints
- Do not claim stronger guarantees than [ORDERING_LEVEL].
- If ordering is "none," do not suggest workarounds that imply a hidden order.
- Use precise language: "events for the same [ORDERING_KEY] are delivered in order" is acceptable; "all events are delivered in order" is not unless it is true.
- Acknowledge that network delivery can always introduce apparent disorder.
- Include a warning if consumers must not rely on insertion order or notification arrival time.

## Examples
Good: "Events sharing the same `order_id` are delivered in the order they were persisted. Events for different `order_id` values have no ordering guarantee."
Bad: "All webhooks are delivered in the exact order they occurred."

## Risk Level
High. Incorrect ordering documentation causes data corruption in consumer systems. Every claim must be verifiable against the actual delivery implementation.

To adapt this template, replace each square-bracket placeholder with your platform's concrete values. The [ORDERING_LEVEL] field is the most critical: choose one of the four options and ensure every sentence in the output is consistent with that choice. If your system provides a sequence number or timestamp in the event envelope, specify the exact field name and format in [SEQUENCE_METADATA]. Before publishing the generated documentation, validate it against your actual delivery code—ordering bugs are notoriously subtle and the model cannot inspect your message broker configuration.

This prompt is designed to sit inside a documentation generation or review pipeline, not as a standalone chat interaction. The typical integration point is a CI/CD step that runs when event catalog schemas change, or a docs-platform plugin that drafts ordering explanations for newly registered webhook topics. The harness must supply the event type name, the delivery guarantee level (at-least-once, at-most-once, best-effort ordering), any sequence-number or timestamp fields present in the envelope, and the platform's actual ordering behavior as known to the engineering team. Without these inputs, the model will invent plausible but incorrect guarantees.

Wire the prompt into an application by building a structured input collector that pulls from the platform's event schema registry and delivery configuration. The collector should assemble [EVENT_TYPE], [DELIVERY_GUARANTEE], [ORDERING_FIELDS], [CONSUMER_REORDERING_GUIDANCE], and [PLATFORM_CONSTRAINTS] from source-of-truth systems rather than free-text entry. After the model returns its explanation, run a validation step that checks for forbidden phrases such as 'guaranteed total order,' 'events always arrive in sequence,' or any absolute ordering claim unless the platform genuinely provides it. Flag outputs that fail this check for human review before publication. For high-risk platforms where ordering misunderstandings could cause data corruption, add a second validation that confirms the output explicitly states what consumers must not assume.

Model choice matters here. Use a model with strong instruction-following and low hallucination rates on technical documentation tasks. GPT-4o or Claude 3.5 Sonnet are appropriate defaults. Set temperature to 0.2 or lower to reduce creative variation in safety-critical language. If the platform's ordering semantics are complex (causal ordering, partial ordering with vector clocks), include a retrieval step that pulls the internal engineering design doc or ADR into [CONTEXT] so the model grounds its explanation in the actual implementation rather than general webhook patterns. Log every generated explanation with its input parameters, model version, and validation results so that future audits can trace why a particular ordering claim appeared in public documentation.

Do not publish the model's output directly. Route all generated explanations through a documentation review queue where an engineer who understands the event pipeline can confirm accuracy. The prompt includes a [REVIEW_CHECKLIST] placeholder that the harness should populate with platform-specific ordering edge cases the reviewer must verify. After approval, store the explanation alongside the event schema version it describes. When the schema or delivery guarantees change, re-trigger the prompt with updated inputs and compare the new output against the published version to detect unintended changes in ordering language. Avoid wiring this prompt into a fully automated publish pipeline unless the platform has a comprehensive integration test suite that validates actual event ordering behavior against the documented claims.