API integration guide
Scoping an API integration before building the connector
A connector is not simply “send A to B.” A useful scope states what moves, which system is authoritative, how delivery is triggered, what access exists, and how people detect and recover from incomplete processing.
Flow specification template
- Business object and event: what changed, and what business result should follow?
- Source of truth: which system may create or correct each field?
- Mapping: source field, destination field, type, required status, transformation, and fallback.
- Identity: stable keys used to match existing records; never rely on a display name alone.
- Direction and trigger: one-way or two-way; webhook, schedule, or explicit user action.
- Access: environment, account owner, authentication method, scopes, rotation owner, and test credentials.
- Delivery behavior: expected volume, rate limits, timeouts, duplicates, ordering, retries, and replay.
- Failure ownership: where errors appear, who acts, how processing resumes, and what must not be repeated.
Webhooks and scheduled synchronization answer different questions
A webhook can notify the receiver soon after an event, but receipt is not proof that the business update finished. A receiver should authenticate the sender where the provider supports it, capture a stable event identifier, return within the provider’s expected window, and perform bounded processing with observable outcomes.
A scheduled reconciliation can find missed or corrected records, but adds delay and requires a reliable cursor or time-window strategy. Some integrations benefit from both: webhook delivery for responsiveness and periodic reconciliation for completeness. The actual API contract decides what is possible.
Duplicates, order, and safe recovery
- Define an idempotency or deduplication key and how long it remains known.
- Use a destination-supported idempotency key or unique constraint so a retry cannot repeat the business side effect. Where you control the destination, an atomic boundary can commit the update and its completion marker together.
- A completion record written separately before acknowledgement cannot by itself prevent a duplicate side effect if the process crashes after the destination update but before that record. It does not provide generic exactly-once delivery; treat ambiguous outcomes with safe replay, reconciliation, or a visible manual-review path.
- Do not assume events arrive in business order; fetch current state when the provider recommends it.
- Separate malformed, unauthorized, temporary, and permanent failures.
- Use bounded retries for temporary failures; send exhausted or permanent failures to a visible review path.
- Give authorized staff a replay procedure that records who approved it and prevents an accidental second update.
Acceptance cases
- A valid new event creates the expected mapped update.
- The same event delivered twice causes one business update.
- An older event arriving later does not overwrite newer authoritative state.
- A malformed or unauthenticated event is rejected without changing the destination.
- A destination timeout becomes visible and can be retried safely.
- A mapping or access change has a named owner and a regression test.
Synthetic educational demo
Browser-local event processing demonstration
This deterministic scenario runs only in your browser. It is not AI, a real integration, customer data, or a client result. It sends and stores nothing.
Mock destination state
Human approval is required before the mock destination is updated.
| Event | Expected outcome |
|---|---|
| evt_1001 — valid | Validated, then held for human approval. |
| evt_1001 — duplicate | Detected by event ID; no second update. |
| evt_bad — malformed | Rejected; no update. |
Source and scope
Stripe documentation: Webhooks. Stripe documents its own signature, duplicate-delivery, retry, and event-order behavior. It is a concrete engineering example, not a claim that every API behaves the same or that Stripe is available or appropriate for a particular business.
