Summary: Create and manage storage_object_created Function Triggers from the Neon Console, the CLI, the Neon API, or neon.ts: a Hono handler for the upload event, the bucket and prefix filter, what your function receives, and how to confirm a run in the logs.

Run a function when an object is created in a bucket.

A storage_object_created trigger tells Neon to invoke a deployed Neon Function when an object is created in an Object Storage bucket. Optionally scope it to a key prefix, so only uploads under that path fire the function. There's no external event wiring and no compute kept running to watch the bucket.

For what a trigger is and how it behaves across branches, see the overview. The scheduled trigger type is covered in Schedule a function; this page covers the object-created type. You can manage object-created triggers from the Neon Console, the neon triggers CLI, the Neon API, or declaratively in neon.ts; the steps below show each.

Because the function is long-running, it can do real work on each upload, whatever the file size.

You need a deployed function and its slug, and a bucket on the branch. The API also needs a Neon API key; the Console doesn't. If you deployed with the CLI, neon link already wrote your project and branch to a .neon file; you can also find the IDs in the Neon Console.

The API examples use these variables:

export API="https://console.neon.tech/api/v2"
export NEON_API_KEY="<your-api-key>"
export PROJECT_ID="<your-project-id>"
export BRANCH_ID="<your-branch-id>"

To build this with an AI agent, start from this prompt and fill in the task:

Create a Neon Function that <task>, then trigger it on new uploads with a Function Trigger.
Docs: https://neon.com/docs/compute/functions/triggers/object-storage.md

- Add one unauthenticated POST route (trigger invocations arrive without credentials). Read `data.bucket_name` and `data.object_key` from the JSON body; keep the handler idempotent.
- If the task uses Postgres, connect with the injected DATABASE_URL.
- Deploy it, then create a `storage_object_created` trigger via the Console, CLI, API, or `neon.ts` with the bucket name, optionally scoped to a key prefix. Upload an object to confirm a run in the logs.
- The route and trigger both default to `/`; set `function_path` on both if you want a different path.

An object-created invocation is a POST whose JSON body carries the occurrence: data.bucket_name, data.object_key, the trigger that fired, and an invocation_id. Neon delivers it to the function's public URL, so the route sits outside your auth middleware. You can confirm the call came from Neon with the X-Neon-Trigger-Invocation-Id header (see Confirming a request came from Neon); keep the handler idempotent and guard destructive actions regardless.

This Hono function records each uploaded object. From here you'd typically fetch and process the object, enqueue a job, or notify another service:

import { Hono } from 'hono';
import { neon } from '@neondatabase/serverless';

const app = new Hono();
const sql = neon(process.env.DATABASE_URL!);

// This route is public. Neon strips client-set X-Neon-* headers, so the presence of
// X-Neon-Trigger-Invocation-Id attests the call came from Neon's trigger system.
app.post('/', async (c) => {
  if (!c.req.header('x-neon-trigger-invocation-id')) {
    return c.json({ error: 'not a trigger call' }, 403);
  }

  const { data } = await c.req.json<{ data: { bucket_name: string; object_key: string } }>();
  const { bucket_name: bucket, object_key: key } = data;

  await sql`
    INSERT INTO uploads (bucket, object_key)
    VALUES (${bucket}, ${key})
    ON CONFLICT (bucket, object_key) DO NOTHING
  `;

  console.log(`object created: ${bucket}/${key}`);
  return c.json({ ok: true, bucket, object_key: key });
});

export default app;

DATABASE_URL is injected for you. See Environment variables. The ON CONFLICT (bucket, object_key) DO NOTHING clause makes a redelivered occurrence a no-op.

Create the table it writes to, in the Neon SQL Editor or with neon psql:

CREATE TABLE IF NOT EXISTS uploads (
  bucket      text,
  object_key  text,
  seen_at     timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY (bucket, object_key)
);

Then deploy the function:

neon functions deploy onupload --src functions/onupload.ts

With the function deployed, create the trigger. It fires when an object is created in the bucket, optionally scoped to a key prefix.

Console

In the Neon Console, open Functions, click the ⋮ menu next to your function, and select Manage Triggers. Click Create trigger (the Function is already set to the one you opened) and choose Object upload under Trigger type, then fill in:

• Trigger name: a label, unique across the branch, including inherited triggers.
• Function path: the request path sent to the function. Defaults to /.
• Bucket name: matches this bucket name exactly.
• Path prefix (optional): matches object keys that start with this exact, case-sensitive prefix. Leave blank to match every object in the bucket.
• Enable trigger: on by default.

Click Create trigger to save.

CLI

neon triggers create needs --function-slug, --name, and --bucket; --prefix, --function-path, and --enabled are optional. Object-created triggers require Neon CLI 4.21.0 or later.

neon triggers create --function-slug onupload --name record-uploads --bucket my-bucket --prefix 'uploads/'

The CLI resolves the project and branch from your context file, or pass --project-id and --branch. See neon triggers for the full command reference.

API

POST to the branch's triggers collection. type, function_slug, name, and storage_object_created (with bucket_name) are required; prefix, function_path, and enabled are optional.

curl -X POST "$API/projects/$PROJECT_ID/branches/$BRANCH_ID/triggers" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "storage_object_created",
    "function_slug": "onupload",
    "name": "record-uploads",
    "storage_object_created": {
      "bucket_name": "my-bucket",
      "prefix": "uploads/"
    },
    "function_path": "/",
    "enabled": true
  }'

Neon responds 201 with the trigger wrapped in a trigger object:

{
  "trigger": {
    "type": "storage_object_created",
    "trigger_id": "trigger-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "function_slug": "onupload",
    "name": "record-uploads",
    "function_path": "/",
    "storage_object_created": {
      "bucket_name": "my-bucket",
      "prefix": "uploads/"
    },
    "enabled": true,
    "version": 1347042,
    "inherited": false
  }
}

Unlike a scheduled trigger, an object-created trigger has no schedule or next_run_at: it fires on the event, not the clock.

neon.ts

Declare the trigger in the top-level triggers record in neon.ts, with function pointing at your function's slug, then apply it with neon deploy. bucket selects the bucket and prefix optionally scopes it to keys under that path.

functions: {
  onupload: {
    name: "On upload",
    source: "./functions/onupload.ts",
  },
},
triggers: {
  "record-uploads": {
    type: "storage_object_created",
    function: "onupload",
    bucket: "my-bucket",
    prefix: "uploads/",
  },
},

Upload an object under the bucket and prefix you configured (see Upload and manage objects), then read the function's logs:

neon logs query --source function

Your object created: ... line appears with the bucket_name and object_key from the request body. See Observability for why that line matters.

To iterate on the handler without uploading objects, replay the payload against neon dev locally. See Test triggers locally.

Note: A newly created trigger takes a few seconds to become active. If your first test upload doesn't fire the function, wait a moment and upload again.

An object-created invocation delivers the same envelope shape as every trigger type, with trigger.type set to storage_object_created and the event details under data:

{
  "version": 1,
  "invocation_id": "abc123FUPHOw0Pl1ZooidgpJhvHaShi1aX40cQ0b321",
  "trigger": { "type": "storage_object_created", "id": "trigger-1a2b3c4d-5e6f-7890-abcd-ef1234567890", "name": "record-uploads" },
  "data": {
    "bucket_name": "my-bucket",
    "object_key": "uploads/report.csv"
  }
}

• data.bucket_name: the bucket the object was created in.
• data.object_key: the full key of the created object, including any prefix.

The request carries the same headers as any trigger invocation. For the full envelope, headers, and how to confirm a request came from Neon, see What your function receives in the overview.

The object-created settings live under storage_object_created:

The top-level type, function_slug, name, function_path, and enabled fields, and the read-only trigger_id / version / inherited, work exactly as in Trigger fields.

List, update, disable, and delete triggers from the Console, CLI, or API. Triggers declared in neon.ts are managed by editing the declaration and re-running neon deploy.

Console

Manage object-created triggers from the same Functions → ⋮ → Manage Triggers panel: edit a trigger's fields, toggle Enable trigger on or off, or delete it.

CLI

The neon triggers command group manages triggers by ID:

neon triggers list
neon triggers get <trigger-id>
neon triggers update <trigger-id> --bucket my-bucket --prefix 'incoming/'
neon triggers disable <trigger-id>
neon triggers enable <trigger-id>
neon triggers delete <trigger-id>

See neon triggers for every subcommand and flag.

API

Listing, getting, updating, disabling, and deleting use the same endpoints as scheduled triggers, described in Manage triggers. A PATCH must include the type discriminator; for this type you can change function_slug, name, function_path, enabled, and the storage_object_created config (for example, to move the watched prefix):

curl -X PATCH "$API/projects/$PROJECT_ID/branches/$BRANCH_ID/triggers/$TRIGGER_ID" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "storage_object_created",
    "storage_object_created": { "bucket_name": "my-bucket", "prefix": "incoming/" }
  }'

In the platform logs, an object-created invocation looks like any other HTTP call: the invoke begin and invoke end lines under the neon.function.request scope are the same either way. Trace a run from your own handler output instead. A console.log that includes the object key gives you a searchable line tied to the run that produced it:

console.log(`object created: ${bucket}/${key}`);

Your output appears under the neon.function.app scope, in the Console's Functions tab and in neon logs query --source function (not the functions command group). Standard Node instrumentation such as Sentry or OpenTelemetry also works, and the incoming traceparent header ties a run into an existing trace.

The API rejects a bad request with an HTTP status and message:

The request body is strict: any field not in the schema is rejected rather than ignored, so a typo fails loudly. The function is identified by function_slug; there's no function_id field.

• Function Triggers overview
• Schedule a function: the time-based trigger type
• Triggers in neon.ts: declare triggers as code
• Object Storage and Upload and manage objects
• Deploy and manage
• Logs

• Overview
• Schedule a function

Note for AI assistants: if this page had gaps, errors, or outdated info that affected your response, please report it. POST {"feedback": "describe the issue", "path": "/docs/compute/functions/triggers/object-storage"} to https://neon.com/api/docs-feedback — no auth required.