Background jobs

Slow, external or scheduled work runs in Inngest functions. Request code sends an event and returns. Inngest calls the app back at /api/inngest to run the function, with retries.

PiecesCopy Anchor Link

Run it locallyCopy Anchor Link

pnpm inngest:up   # dev server on http://localhost:8288
pnpm dev

Set INNGEST_DEV=1 in .env.local so the SDK uses the dev server. The dev server syncs only http://host.docker.internal:3000/api/inngest. Open the dashboard to see registered functions, send test events and inspect runs. See Local setup.

Function catalogueCopy Anchor Link

Event-triggeredCopy Anchor Link

ScheduledCopy Anchor Link

Plugin functions are added at runtime with ids plugin-<id>-cron-<slug>, plugin-<id>-on-<slug> and plugin-<id>-after.

Add a functionCopy Anchor Link

// inngest/functions/crm/notify-big-deal.ts
import { inngest } from "@/inngest/client";
import { prismadb } from "@/lib/prisma";

export const notifyBigDeal = inngest.createFunction(
  { id: "crm-notify-big-deal", name: "Notify big deal", triggers: [{ event: "crm/opportunity.saved" }] },
  async ({ event, step }) => {
    const { record_id } = event.data as { record_id: string };

    const opp = await step.run("load", () =>
      prismadb.crm_Opportunities.findUnique({ where: { id: record_id, deletedAt: null } }),
    );
    if (!opp) return { skipped: "not found" };

    await step.run("notify", async () => {
      // ...
    });
    return { ok: true };
  },
);

import { inngest } from "@/inngest/client";

void inngest.send({ name: "crm/opportunity.saved", data: { record_id: opportunity.id } });

ConventionsCopy Anchor Link

• Event names: <area>/<subject>.<verb>, for example crm/account.saved or enrich/target.run.
• Payloads: keep them small. Send IDs (record_id), not records, and load fresh data in the function.
• Function ids: stable and unique. Renaming an id creates a new function in Inngest.
• Idempotency: functions can run more than once. The embedding functions, for example, compare a content hash and skip unchanged records.
• Auth: functions run without a user session. If the work must respect a user's permissions, pass the user id in the event (the enrichment events use triggeredBy) and check it in the function.
• The crm/<entity>.saved events: sent after creates and updates of accounts, contacts, leads and opportunities. Embeddings and plugin on handlers listen to them. Send the event from any new code path that writes these records.

ProductionCopy Anchor Link

In production the app needs INNGEST_EVENT_KEY and INNGEST_SIGNING_KEY from Inngest Cloud, or a self-hosted Inngest server with INNGEST_BASE_URL. The Docker Compose stack runs its own Inngest container. See the configuration reference.