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.

No events processed. The table below remains useful without JavaScript.

Mock destination state

EventExpected outcome
evt_1001 — validValidated, then held for human approval.
evt_1001 — duplicateDetected by event ID; no second update.
evt_bad — malformedRejected; 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.