Subchapter 3.2

Function Triggers

references/function-triggers.mdMarkdown11 KBView on GitHub

A Function Trigger is a branch-scoped rule that POSTs to a Neon Function so recurring work does not need a separate scheduler. The request is a normal fetch invocation: same public URL, same 15-minute time-to-first-byte limit, same injected env (DATABASE_URL, …).

Same regions as Functions: aws-us-east-2, aws-us-east-1, aws-eu-central-1, and aws-ap-southeast-1. Needs Neon CLI 4.21 or newer to declare triggers in neon.ts.

If neon deploy returns 404 function triggers not available for this project, the project does not have Function Triggers yet. Deploy the function without applying the trigger (neon functions deploy <slug> --src <entry>) and retry neon deploy once the project has them.

Supported types

Function Triggers · Neon Functions · neondatabase/agent-skills · Skills Docs

`type`	When it fires	`neon.ts` fields	CLI create
`schedule`	On a five-field UTC cron expression	`function`, `cron`	`neon triggers create --cron '…'`
`storage_object_created`	When an object is created in a declared bucket	`function`, `bucket`, optional `prefix`	`neon triggers create --bucket <name>`

Field	Required	Notes
`type`	yes	`"schedule"` or `"storage_object_created"`
`function`	yes	Function slug. REST/MCP: `function_slug`
`cron`	schedule	Five-field UTC expression, e.g. `0 * * * `, `/15 * * * *`
`bucket`	storage	Bucket name. REST: `storage_object_created.bucket_name`
`prefix`	no	Object-key prefix filter. REST: `storage_object_created.prefix`
`functionPath`	no	Path on the function. Default `/`. CLI: `--function-path`
`enabled`	no	Default `true`. CLI: `--enabled false` to create disabled

import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  functions: {
    ingest: { name: "Object ingest", source: "src/index.ts" },
    cron: { name: "Cron", source: "src/cron.ts" },
  },
  buckets: { assets: { access: "public_read" } },
  triggers: {
    "on-upload": {
      type: "storage_object_created",
      function: "ingest",
      bucket: "assets",
      prefix: "logos/",
      functionPath: "/object",
    },
    "every-minute": {
      type: "schedule",
      function: "cron",
      cron: "* * * * *",
      functionPath: "/cron",
    },
  },
});

neon triggers create --function-slug cron --name hourly --cron '0 * * * *' --function-path /cron
neon triggers create --function-slug ingest --name on-upload --bucket assets --prefix 'logos/' --function-path /object
neon triggers list
neon triggers list --output json
neon triggers update <id> --branch <branch> --cron '*/30 * * * *'
neon triggers update <id> --branch <branch> --bucket assets --prefix 'incoming/'
neon triggers enable <id> --branch <branch>
neon triggers disable <id> --branch <branch>
neon triggers delete <id> --branch <branch>

{
  "version": 1,
  "invocation_id": "…",
  "trigger": {
    "type": "storage_object_created",
    "id": "trigger-…",
    "name": "on-upload"
  },
  "data": { "bucket_name": "uploads", "object_key": "smoke.txt" }
}

import { parseTriggerDelivery } from "@neon/functions/triggers";

export default {
  async fetch(request: Request): Promise<Response> {
    const parsed = await parseTriggerDelivery(request);
    if (!parsed.ok) {
      const status = parsed.error === "invalid_body" ? 400 : 401;
      return new Response(parsed.error, { status });
    }

    const invocation = parsed.invocation;
    if (invocation.type === "storage_object_created") {
      return Response.json({
        bucketName: invocation.data.bucketName,
        objectKey: invocation.data.objectKey,
      });
    }

    return Response.json({
      scheduledAt: invocation.data.scheduledAt,
    });
  },
};

Failure	Status	Message
missing header	401	`Missing x-neon-trigger-invocation-id header`
header ≠ `invocation_id`	401	`Invocation id mismatch`
invalid JSON or payload	400	`Invalid trigger payload`

import { parseTrigger } from "@neon/functions/hono";

app.post("/cron", async (c) => {
  const invocation = await parseTrigger(c);
  return c.json({ ok: true, invocationId: invocation.invocationId });
});

import { parseTriggerInvocation } from "@neon/functions/triggers";

export default {
  async fetch(request: Request): Promise<Response> {
    const parsed = await parseTriggerInvocation(request);
    if (!parsed.ok) {
      const status = parsed.error === "invalid_body" ? 400 : 401;
      return new Response(parsed.error, { status });
    }
    return Response.json({
      ok: true,
      invocationId: parsed.invocation.invocationId,
    });
  },
};

curl -X POST http://localhost:8787/cron \
  -H 'content-type: application/json' \
  -H 'x-neon-trigger-invocation-id: local-dev' \
  -d '{
    "version": 1,
    "invocation_id": "local-dev",
    "trigger": { "type": "schedule", "id": "trigger-local", "name": "hourly" },
    "data": { "scheduled_at": "2026-09-15T00:00:00Z" }
  }'

Function Triggers

Supported types

Function Triggers

Supported types

Fields

neon.ts (preferred)

CLI

MCP backup

Delivery payload

`parseTriggerDelivery` (both types)

`parseTrigger` (Hono, schedule only)

`parseTriggerInvocation` (`fetch`, schedule only)

Local `neon dev`

Inheritance

Logs