Async-First Resource Lifecycle

All Infinia APIs are async-first and follow a consistent resource lifecycle. For any given resource, you should expect:

Create endpoint
Creates the resource and returns its initial representation.
Retrieve / List endpoint
Returns the latest known state of the resource.
Webhook events
Notify you of state changes by POSTing the resource to your webhook endpoint.

📘
Create responses, retrieve/list endpoints, and webhook payloads all share the same object schema. This allows you to reuse parsing, validation, and business logic across synchronous and asynchronous flows.

Webhooks for State Updates

Infinia APIs are designed to be event-driven.

For tracking state changes (e.g. completion, failure, rejection), developers are strongly encouraged to rely on webhooks. Webhooks provide:

Near-real-time updates
Automatic retries on delivery failures
A scalable way to stay in sync without constant API calls

Using webhooks avoids unnecessary polling and helps reduce avoidable load on both your systems and ours.

Polling as a Fallback

Polling retrieve endpoints should be used only as a fallback, for example:

If a webhook delivery fails and needs reconciliation
To backfill state after a temporary outage

Polling is not recommended as the primary mechanism for tracking updates, as it introduces unnecessary latency and infrastructure load.

Idempotency & Safe Retries

Certain operations are considered sensitive, including but not limited to:

Sending payouts
Performing internal transfers
Any operation that moves funds or changes balances

These operations require an external identifier (e.g. external_id), which also serves as an idempotency key.

How Idempotency Works

Idempotency is enforced at the application level, not the HTTP level.

This means that if you:

Encounter a network timeout
Receive a 5xx error
Lose the response before it reaches your system

You can safely retry the request using the same idempotency key, and the API will return the final result of the original operation, rather than re-executing it or repeating the error.

This makes retries safe and predictable in the presence of network or infrastructure failures.

Recommended Integration Pattern

Generate and persist a unique external ID for each sensitive operation
Retry requests that fail due to network or transport errors (such as timeouts or 5xx responses) using the same external ID
Idempotency applies to request delivery, not to business outcomes
Rely on webhooks for receiving state updates
Use retrieve endpoints only to reconcile or recover state when needed

Feedback & Developer Contact

We welcome feedback and suggestions from developers.

If you have questions, ideas, or encounter unexpected behavior, feel free to reach out:

📧 devs@infiniaweb.com