new-integration

To wrap external APIs into domain integrations, you create a module under src/domain/integrations that exposes a domain-oriented API, uses config files for provider settings, and maps errors to a common type. This hides provider specifics from your application services.

Handling API rate limits and retries is managed within the integration layer by configuring HTTP client timeout and retry strategies. This encapsulates the resilience logic inside the domain integration rather than scattering it across services or jobs.

You map API errors by converting third-party provider responses into a common application error type within the integration module. This ensures that services and event listeners handle a uniform error structure instead of provider-specific exceptions.

Yes, you can use config files to manage API provider settings by placing them in config/<provider>.toml with optional .env overrides. This config-driven approach allows distinct HTTP client setups and credentials for each external service.

You route incoming webhooks by wiring dedicated verification and routing paths via new-route. This allows event-driven usage where webhooks from providers trigger specific domain integration logic securely.

Yes, this pattern works for integrating services like Stripe, Twilio, Mailgun, and KYC/OAuth providers. It applies to any third-party HTTP API by standardizing request/response structures and webhook handling across all providers.