Service integrations

This reference service connects scheduled jobs, incoming events, and application requests to a small set of external operations. Examples include creating a ticket, refreshing reference data, or preparing a report. Each connector declares its allowed destinations, operations, access scope, timeout, and accountable owner.

Assume independently failing systems and asynchronous completion. Record acceptance, execution, and final outcome separately. A request accepted into a queue is not evidence that its destination completed the work.

Authenticate application calls and verify webhook signatures against the unmodified payload, following the provider's contract. A mailbox sender label is not sufficient authority for a command. Resolve allowed actions and resources on the server; arbitrary URLs, scripts, or destination credentials are not accepted as request parameters.

Give accepted work a durable receipt tied to a provider event ID or client operation key. Store the intended action and arguments with that identity. Repeated delivery returns the existing receipt; reuse with different arguments is a conflict. Persist the receipt and pending-dispatch record in one transaction. A dispatcher retries queue publication using the same operation identity, so a restart cannot strand accepted work. Only acknowledge work after that transaction commits. Reconcile source progress because not every provider retries missed deliveries.

Use a service identity where the provider supports it. User-delegated access has its own consent, expiry, and revocation rules. Keep access and refresh tokens in restricted storage, bind them to the intended resource and scope, and exclude them from job logs and notifications.

When refresh tokens rotate, coordinate concurrent refresh attempts and atomically store the replacement. A lost response may leave the old token unusable; follow the provider's recovery contract rather than repeatedly presenting it. Revocation or lost consent stops affected work and requests reconnection. It must not silently switch to a more privileged identity.

A worker receives a versioned operation and narrowly scoped credentials. Recheck current authorization before consequential execution. Where approval is required, bind it to the resolved target and arguments; changing either requires another decision. Limit concurrency, connection use, and outbound request rate per dependency.

Use a stable destination idempotency key where supported. After a timeout, an operation may have succeeded remotely. Query its recorded state before retrying. If the destination cannot deduplicate or reveal the outcome, assign reconciliation to a person. A local receipt alone cannot prevent a second external effect.

Expose an authenticated status endpoint with accepted, running, succeeded, failed, canceled, and uncertain states. Preserve attempt history and the last useful progress time. Cancellation records what has stopped and any effects that already occurred.

Retry transient failures within a bounded budget, honoring provider backoff guidance. Sending a notification has its own delivery outcome; it must not change whether the underlying job succeeded. Messages contain a short status and an access-controlled link, with sensitive results available only through the application.

Monitor queue age, expired credentials, provider limits, repeated failures, unresolved outcomes, and notification backlog. A replay uses the recorded operation identity and an explicit recovery decision. Test credential rotation, duplicate events, permission revocation, destination timeouts, and a restart after dispatch.

This service adds state, connector upkeep, and operational responsibility. For occasional work, a reviewed manual process or a managed integration may be sufficient. The deciding question is whether repeated coordination and recovery justify maintaining a shared service.