From a Document to a Useful Passage: The Retrieval Pipeline
October 18, 2026
Did the Change Help? Metrics, Baselines and a Trustworthy A/B Test
October 18, 2026
Receiving a message and completing the work are different steps. AI-generated illustration.
Two applications exchange a message and someone says, “The integration worked.” What actually happened? The message might have arrived, passed a format check or caused a useful task to be created. Those are different observations. Following one event makes the vocabulary easier to connect to evidence.
The interface defines how software can interact
An application programming interface, or API, provides defined features and rules for software interaction. MDN describes it as a contract between the application and other software or hardware. An API is therefore broader than a web address: its interface describes the interaction available to a program.
An integration connects applications within a shared process. GitHub’s integration documentation gives a concrete example of the distinction: an integration can use its API to request or change data and use webhooks to learn about events. The integration is the working connection; an API and an event notification can be parts of it.
For a particular connection, the contract needs to specify what an operation means, which information it expects and what its response establishes. A field named “ready” is not enough unless both sides agree what is ready and what the receiver may do next. These meanings belong to the application’s design.
One fictional draft moves toward review
Imagine an editing application, A, and a review tracker, B. A records that a draft is ready for review. B is intended to create a pending review task for that draft. The applications, document and message are invented. Nothing here has been sent, connected or tested against a live service, and readiness for review does not mean approval to publish.
For this teaching example, the message must name the event, a document reference and a positive integer revision. The event must be “draft_ready.” The document reference must correspond to a document that the receiving process is allowed to handle. This is our illustrative contract, not a provider’s payload specification.
{
"event": "draft_ready",
"document": "example_note",
"revision": 2
}JSON, short for JavaScript Object Notation, is a text format for exchanging structured data. MDN’s JSON definition describes objects, arrays, strings, numbers, booleans and null. The example is a small data object; it is not executable integration code or a complete request to any real interface.
Syntactically valid JSON only establishes that a parser can read its structure. Replacing the numeric revision with the string “two” would still be valid JSON, but would violate our positive-integer rule. An unknown document reference could have the right type while failing the business check. Neither successful parsing nor those field checks establish the sender’s authority.
Distinguish asking for work from announcing an event
A request asks an interface to perform a defined operation or return information. An event notification reports that something happened. In the fictional process, “draft_ready” reports the editing application’s state. The receiver still needs an explicit rule connecting that event with creation of a review task. The message does not carry unlimited authority just because its event sounds useful.
A webhook delivers an event notification to a configured receiver. GitHub’s webhook explanation describes subscribing to events and receiving an HTTP request with event data when one occurs. That delivery is itself a request to the receiver; the distinction concerns what the message means, not a claim that notifications use a separate kind of transport.
Polling instead checks an API intermittently for available data or changes. With a webhook, the event source sends the notification to the configured receiver. GitHub documents this contrast for its integrations. Choosing a pattern still requires the actual interface’s delivery and access rules; the words alone do not promise a particular notification delay or complete event history.
In our fictional design, A could notify B that a draft is ready, while B uses a permitted lookup to obtain the relevant draft details. The event and the lookup have separate purposes. If the lookup cannot establish which revision is ready, the review task should remain unresolved rather than quietly using a different revision.
Define what each acknowledgement actually proves
For this illustration, a receipt means only that the message reached B’s receiving process. A separate recorded outcome confirms that a pending review task exists. Those meanings are deliberate assumptions for our example, not universal interpretations of an HTTP status or a provider’s response. The integration needs observable evidence for the outcome it promises.
| Checkpoint in the fictional transfer | Evidence it provides | What remains separate |
|---|---|---|
| JSON parsed | The message has readable JSON syntax | Correct values and sender authority |
| Contract checks passed | The stated field and business rules were checked | Whether the requested work completed |
| Receipt recorded | B acknowledged receiving the message | Whether a review task exists |
| Pending review task recorded | The defined workflow milestone was reached | Approval or publication of the draft |
If no receipt is visible, the outcome is unknown. Before resending, the operators would need the actual provider’s rules for delivery, retries, ordering and duplicates, plus a way to inspect the receiving process. The term webhook does not establish exactly-once processing. In the fictional workflow, repeated notifications should not silently be interpreted as requests for additional reviews.
Likewise, accepting a connection should not erase permission boundaries. Authentication and authorization need to be checked under the actual interface and application rules. A JSON field cannot grant itself permission to publish. In this example, B’s permitted outcome is a pending task for a reviewer; the reviewer’s decision remains a later step.
From AI Demo to Reliable Workflow extends this idea to the surrounding process: define the input and output contract, make failures visible and name the next responsible role. When reading an integration result, ask which boundary has actually been crossed—message format, accepted operation, receipt or business outcome—and keep the next unverified step explicit.
If the acknowledgement never arrives, read when a timed-out request should be reconciled, retried or stopped before creating the work again.
