Technology handbook
Inngest services
Durable event-driven functions with steps, retries, concurrency, flow control and observability.
- Topics
- 32
- Sections
- 5
Hooks
useRealtime
Subscribe a component to a function's realtime channel and topics, using a server-issued token.
- Subscribe with useRealtime from the installed React SDK entry point.
- Supply the typed channel, topics and server-issued subscription token.
- Handle reconnecting and terminal UI states explicitly.
Subscription tokens
Mint a short-lived token on the server so the browser never holds the signing key.
- Mint subscription tokens after authenticating the requesting user.
- Scope each token to authorized channels and topics.
- Keep the application's signing key out of browser code.
step.realtime.publish
Publish durably from inside a step, so a retry does not send the message twice.
- Publish important state transitions through a durable realtime step.
- Give each publish step a stable memoization identifier.
- Use ordinary realtime publishing for updates where replay is acceptable.
onFunctionRun
Middleware that wraps a whole run: attach a logger, a tenant, a trace.
- Attach run-scoped behavior through the SDK's function lifecycle hook.
- Add correlation or dependencies to the execution context.
- Avoid assuming a hook executes only once across retries.
onStepRun
Middleware around each step, where per-step timing and context belong.
- Use step lifecycle middleware for timing and tracing step work.
- Distinguish executing a step from reusing a saved result.
- Make cleanup and instrumentation tolerant of retried execution.
transformInput and transformOutput
Change what a function receives and returns without editing the function.
- Transform incoming context and outgoing results at documented boundaries.
- Preserve the shapes expected by subsequent middleware.
- Test ordering when multiple transforms modify the same field.
onSendEvent
Intercept outgoing events to add metadata or redact fields centrally.
- Observe or transform event publication at the send boundary.
- Preserve event names, IDs and validated payload fields.
- Do not log secret values while tracing outbound events.
wrapStep
Wrap step execution itself - the hook to reach for when per-step behaviour must compose.
- Wrap supported step execution through the installed middleware API.
- Call the wrapped operation and preserve its result or error.
- Keep tracing wrappers compatible with cancellation and retries.
Functions & steps
Events and triggers
Start a function from an event, a schedule or another function.
- Publish an event name and structured data describing what happened.
- Match function triggers to the intended event contract.
- Include stable domain identifiers for correlation.
Function definition
Declare an id, a trigger and the handler that runs.
- Give each function a stable ID and explicit trigger configuration.
- Keep durable work inside the function's supported step tools.
- Configure retries and flow control for its dependencies.
step.run
Wrap a side effect so its result is stored and never repeated.
- Wrap one retryable unit of work in step.run.
- Use a stable step ID within the function's execution path.
- Return serializable data needed by later steps.
Step memoization
Understand replay, and why code outside a step is not safe.
- Completed step results can be reused when a function resumes.
- Keep nondeterministic work inside named steps.
- Treat changes to step identity as workflow compatibility changes.
step.sleep and sleepUntil
Pause for a duration or until a moment without holding a process.
- Use durable sleeps instead of keeping a process timer alive.
- Choose a duration or absolute wake-up time deliberately.
- Account for cancellation while a function is sleeping.
step.waitForEvent
Suspend until a matching event arrives or a timeout expires.
- Wait for a matching event with an explicit timeout.
- Correlate the event to the relevant user or workflow.
- Handle the timeout result as a normal alternate path.
Reliability
Automatic retries
Let a failed step retry with backoff instead of failing the function.
- Throw failures that should trigger another attempt.
- Keep external side effects idempotent across retries.
- Bound retries according to the dependency's failure behavior.
Non-retriable errors
Signal a permanent failure so the platform stops retrying.
- Use the SDK's non-retriable error for permanent failures.
- Separate invalid input from transient network problems.
- Include diagnostic context without exposing confidential event data.
Idempotency
Deduplicate by event key so one logical event runs once.
- Choose an idempotency expression tied to the business operation.
- Understand the configured deduplication window and scope.
- Enforce unique side effects in the destination system too.
Failure handlers
React when a function exhausts its retries.
- Handle exhausted function failures through the supported failure path.
- Include the original event and run identity in diagnosis.
- Make alerting or compensation safe to retry itself.
Cancellation
Stop an in-flight function when a cancelling event arrives.
- Cancel obsolete runs when a matching business event arrives.
- Scope cancellation to the correct entity or workflow.
- Design already-completed side effects to remain consistent.
Timeouts
Bound how long a step and a function may take.
- Set start and execution deadlines appropriate to the workflow.
- Distinguish waiting for capacity from running too long.
- Report timed-out work with enough context for recovery.
Flow control
Concurrency limits
Cap parallel runs globally or per key such as per customer.
- Limit active work by function or an appropriate keyed scope.
- Protect database and provider capacity from event bursts.
- Monitor queueing time as well as execution time.
Throttling and rate limiting
Respect a downstream API's limits from inside the function.
- Throttling smooths work over time instead of starting it all at once.
- Rate limits reject or suppress starts according to configured policy.
- Choose keys so one tenant cannot consume every allocation.
Debounce
Collapse a burst of events into a single run.
- Collapse repeated events within a configured quiet period.
- Key debounce by the entity whose updates supersede each other.
- Avoid debouncing events that each require an independent side effect.
Batching
Process events in groups to amortize a costly operation.
- Collect related events into a bounded processing batch.
- Choose batch size and timeout to balance latency and throughput.
- Handle partial failures without losing successful event results.
Priority
Run urgent work ahead of background work in the same queue.
- Assign priority from trusted event or application attributes.
- Prevent low-priority jobs from starving indefinitely.
- Confirm priority behavior within the configured concurrency scope.
Fan-out
Trigger many functions from one event without coupling them.
- Split independent work into separately tracked steps or events.
- Bound fan-out so downstream quotas remain respected.
- Collect child outcomes before declaring the parent operation complete.
Development & operation
Local dev server
Run and inspect functions locally against real event payloads.
- Connect the development server to the local serve endpoint.
- Send representative events and inspect run traces.
- Keep local test events separate from production event traffic.
Serving the handler
Expose functions through a route in your framework.
- Expose the framework-specific Inngest serve handler.
- Register the intended function list at that endpoint.
- Configure signing and environment keys for deployed execution.
Event schemas
Type events so producers and consumers agree on the payload.
- Validate event names and payload fields at the producer boundary.
- Version contracts when consumers need incompatible data shapes.
- Remember static types do not validate untrusted runtime JSON.
Observability
Trace a run step by step and see exactly where it failed.
- Trace events into function runs and individual steps.
- Compare queue delays, retry counts and dependency latency.
- Attach business identifiers while keeping logs appropriately redacted.
Replay
Re-run historical events after fixing a bug.
- Replay a known event or run to diagnose recovery behavior.
- Confirm whether memoized results or side effects will be reused.
- Keep replayed operations idempotent and auditable.
Environments
Separate branch, staging and production event streams.
- Separate development, preview and production credentials and data.
- Register functions against the matching environment.
- Verify event routing before promoting a deployment.
Sources
- Inngest services official documentation