Inngest

The event, postPublishedEvent, defines both the event’s name ("post.published") and the shape of its payload, PostPublishedData, typed and validated through staticSchema. The client, inngest, is what you send events through, and what workers register against.

The worker is what actually does the work, in this case calling the exact same sendPostNotifications() function used elsewhere in the notifications system. retries controls Inngest’s own retry mechanism, separate from anything you might write yourself. By default, Oolvay reads this value from siteConfig.backgroundJobs.inngest.retries. If the worker throws, Inngest retries the whole function up to that number of times before giving up.

Workers are registered with Inngest’s own route handler, which both serves local development tooling and receives real invocations in production:

Sending an event does not run the worker directly

dispatchPostNotification() is where a post publish actually triggers this whole chain. It does not call the worker function. It sends an event, and Inngest is what decides when and how the worker runs.

This is the entire fallback story in one place. If inngest.enabled is true, the function fires off an event and returns immediately, regardless of whether the actual email sending takes two seconds or two minutes. If inngest.send() itself fails, that failure is logged and reported to Sentry, but the function does not throw, the publish action that called this is not blocked by a queueing failure.

If inngest.enabled is false, none of the above runs. sendPostNotifications() is called directly and awaited, the same function the worker would have called, just synchronously, on the calling request, with no queue involved.

Disabling Inngest does not lose functionality, it loses concurrency

With inngest.enabled: false, every post publish that should trigger notifications still triggers them, correctly, every time. What changes is that the publishing request now waits for sendPostNotifications() to fully finish, including every batch of emails it sends, before the request completes. For a small number of recipients this is unnoticeable. For a large one, this is exactly the blocking behavior Inngest exists to remove.

This mirrors the same additive pattern as analytics and realtime delivery elsewhere in Oolvay. Disabling Inngest changes how work happens, not whether it happens.

Configuration

inngest.enabled

Controls whether dispatchPostNotification(), and any future code following the same pattern, sends an event to Inngest or runs the underlying work synchronously and in line. This is the only flag that matters for this decision. The three environment variables covered in Environment variables below govern how Inngest itself behaves once you have chosen to use it, not whether you are using it.

inngest.retries

Controls the default number of times Inngest retries a worker when it throws an error.

This value is used by the workers that ship with Oolvay, but it is not a hard requirement. Individual workers can use a different retry count if a particular job has different reliability or side effect requirements.

Use the global value when a worker should follow the application’s default retry policy. Override it when a specific job needs different behavior.

Environment variables

Three separate environment variables exist for Inngest. INNGEST_DEV decides which Inngest environment your app talks to. INNGEST_EVENT_KEY authenticates events going out. INNGEST_SIGNING_KEY authenticates invocations coming in.

INNGEST_DEV switches the SDK to your local Inngest dev server instead of Inngest’s hosted cloud, regardless of whether real credentials are present. It is a development convenience, not a feature flag, and it is unrelated to siteConfig.backgroundJobs.inngest.enabled, which controls whether Oolvay’s own code routes through Inngest at all. Enabling or disabling Inngest in config/site.ts does not change which Inngest environment you are talking to. INNGEST_DEV does.

INNGEST_EVENT_KEY authenticates outbound calls, your application sending events to Inngest. It is used wherever inngest.send() is called.

INNGEST_SIGNING_KEY authenticates inbound calls, Inngest invoking your worker functions through app/api/inngest/route.ts. It is checked by Inngest’s serve() handler, not by your own application code directly.

INNGEST_EVENT_KEY and INNGEST_SIGNING_KEY serve opposite directions of the same conversation and are not interchangeable.

Setting up Inngest

Adding a new Inngest job

The shape is the same every time, regardless of what the job actually does.

Production

INNGEST_DEV=1 and the local dev server are both strictly for local development. Production does not use either.

Remove INNGEST_DEV from your production environment entirely, or set it explicitly to 0. If neither the environment variable nor the equivalent client config option is specified, the SDK defaults to cloud mode, so an unset INNGEST_DEV in production is safe, but an INNGEST_DEV=1 left over from a copied .env file is not, since it would point your production app at a dev server that does not exist there.

Use the Vercel integration instead of setting keys manually

If you deploy on Vercel, install Inngest’s official Vercel integration rather than copying INNGEST_EVENT_KEY and INNGEST_SIGNING_KEY into Vercel’s environment variables yourself. The integration sets both automatically, and resyncs your app to Inngest on every deploy, so your keys never drift out of date the way a manually copied value can.

If you deploy somewhere other than Vercel, set both manually instead.

Disable Deployment Protection, or configure a bypass

Vercel enables Deployment Protection by default on both preview and production URLs. Inngest’s servers cannot reach your /api/inngest endpoint while this is on, since Inngest authenticates using your signing key rather than a Vercel-issued session.

On Vercel’s free tier, disable Deployment Protection for the project. On Vercel’s Pro plan, configure Protection Bypass for Automation instead, and add the resulting secret to the Inngest Vercel integration’s settings so Inngest can use it to reach your app without disabling protection entirely.

Set maxDuration and maxRuntime together

Add maxDuration directly to your existing route handler.

Then set maxRuntime on the client itself, twenty to forty percent below maxDuration. With maxDuration at 300 seconds, a maxRuntime of 200 seconds sits comfortably inside that range.

Checkpointing is enabled by default on the v4 SDK, and lets multiple steps run inside a single request instead of round-tripping to Inngest after every step. Without a maxRuntime set below your platform’s actual timeout, a long-running function risks hitting Vercel’s own timeout before Inngest gets a chance to checkpoint and hand off cleanly.

Common issues

Events are being sent, but the worker never runs

Confirm the worker is actually included in the functions array passed to serve() in app/api/inngest/route.ts. A worker defined but not registered there receives nothing.

Everything works locally, but production silently does not trigger workers

Check INNGEST_SIGNING_KEY specifically. This is the credential Inngest uses to authenticate its calls into your application, and a missing or incorrect value in production will cause invocations to fail even though sending events from your application appears to succeed.

Disabling Inngest seems to have broken nothing, but publishing now feels slower

This is expected, not a bug. With inngest.enabled: false, the work that would have run on Inngest’s infrastructure now runs synchronously, inside the request that triggered it. See Disabling Inngest does not lose functionality, it loses concurrency above.

A failed inngest.send() call does not show up as a failed job anywhere in Inngest’s own dashboard

This is correct, and worth understanding precisely. Inngest’s dashboard only shows jobs it actually received. If inngest.send() itself fails, the event never reached Inngest, so there is nothing for Inngest to show. That failure is reported through your own logger and Sentry instead, inside dispatchPostNotification(), not inside Inngest’s infrastructure.

The bash installer fails with a 404

can fail with curl: (22) The requested URL returned error: 404, pointing at a release zip that does not exist for that version. This is an issue with Inngest’s own installer script or release assets for that specific release, not with your project, and is not confirmed to be limited to any one operating system.

If you already have an inngest binary installed from a previous attempt, inngest dev still works despite the failed install, the script’s only job is to fetch a newer binary, and an older one already on your PATH is unaffected by that failure.

If you have no binary installed yet, skip the script and download the Windows zip directly from Inngest’s GitHub releases, using whichever release actually has a Windows asset attached. Extract inngest.exe and add it to your PATH.

bun dev

Following this branching pattern, rather than calling inngest.send() unconditionally, is what keeps a new job working correctly even for a founder who has not enabled Inngest at all.