| name | external-integration |
| description | Implement a robust external-system integration with contract discovery, authentication, mapping, idempotency, rate limits, retries, observability, and failure isolation. |
External Integration
Use for third-party APIs, webhooks, queues, identity providers, payment/data providers, or system-to-system connectors.
Procedure
- Read authoritative provider documentation and confirm version, auth model, scopes, limits, and lifecycle behavior.
- Define the internal/external contract mapping, including identifiers, types, timezones, pagination, and optional fields.
- Treat remote input as untrusted and validate signatures/authentication for inbound events where supported.
- Design idempotency and deduplication for retried requests or duplicate webhooks.
- Handle rate limits, timeouts, retryable vs permanent errors, partial failure, and provider downtime.
- Keep provider-specific semantics behind a clear adapter boundary when practical.
- Add observability that can trace a failed operation without logging secrets or sensitive payloads unnecessarily.
- Test against sandbox/fixtures and important error responses.
Quality gate
The integration must remain understandable and recoverable when the remote system is slow, duplicated, inconsistent, or unavailable.
