DEV Community: Sascha Mirow-Stanitzok

Temporal API in TypeScript: deadlines and time zones

Sascha Mirow-Stanitzok — Sun, 01 Nov 2026 17:49:02 +0000

Being able to use the Temporal API in TypeScript was one of my favorite pieces of news around Node.js 26. Over the years I have seen plenty of code where a deadline was off by an hour because somebody wrote “plus 48 hours” instead of “plus two days” and a daylight saving change happened in between. Bugs like that don’t show up in tests. They show up in production, twice a year.

In my article on Node.js 26 LTS on Lambda I only touched on Temporal briefly. This time we go deeper: step by step, you build the deadline logic for a fictional city library, store the values cleanly in DynamoDB, deploy everything to Lambda with the Serverless Framework and deliberately test across the DST change. Afterwards you will know which Temporal type is meant for what and how to move away from Date or date-fns.

In short

Temporal replaces Date with dedicated types for instants, calendar dates and times in a time zone. Node.js 26 ships the API without a flag, TypeScript has included the types since version 6.0, and older Lambda runtimes only need a small polyfill. The biggest pitfall is choosing the wrong type: if you store a deadline as a plain date without a time zone, you only move the problem somewhere else.

What you will learn in this article

Which Temporal type is right for instants, calendar days and deadlines
How to set up Temporal in TypeScript, Node.js 26 and on Lambda with nodejs24.x
How to calculate and test deadlines correctly across DST changes
How to store Temporal values in DynamoDB, including TTL
How to migrate step by step from Date or date-fns

Why Date so often gets deadlines wrong

Date has been part of JavaScript since 1995 and was closely modeled on an early Java class at the time. You can still tell. Months start at 0, so new Date(2026, 9, 25) is October 25. A Date object is mutable, and if you pass it to a function you may get it back changed. On top of that, Date knows exactly two time zones: UTC and the local time zone of the machine running the code.

That last point is especially tricky in a Serverless setup. A Lambda function runs in UTC by default. Your customers, however, live in Berlin, Vienna or Zurich. Ask Lambda for “today” at 0:30 am German time and you still get yesterday. Lambda is doing everything right here. The real question is: whose “today” do you mean?

The classic example is the DST change. On October 25, 2026, clocks in Germany go back from 3:00 am to 2:00 am, so that day has 25 hours. If you create a deadline of “two days” on October 24 at 10:00 am and calculate it as 48 hours, you end up at 9:00 am on October 26. What you meant was 10:00 am. That is why Temporal clearly separates exact durations in hours from calendar arithmetic in days.

const pickup = Temporal.ZonedDateTime.from("2026-10-24T10:00[Europe/Berlin]");

console.log(pickup.add({ hours: 48 }).toString());
// 2026-10-26T09:00:00+01:00[Europe/Berlin]  (exactly 48 hours later)

console.log(pickup.add({ days: 2 }).toString());
// 2026-10-26T10:00:00+01:00[Europe/Berlin]  (two calendar days later)

Both results are correct. They simply answer different questions. With Date you have to keep that difference in your head, while Temporal makes you write it down.

Which Temporal type for which purpose?

Temporal is a namespace like Math, not a constructor. It contains several classes, and all objects are immutable: every operation returns a new object. For everyday work you mainly need these types:

Type	What it describes	Typical example
`Temporal.Instant`	Exact point on the timeline, without calendar or time zone	Event timestamp, log entry
`Temporal.ZonedDateTime`	Instant plus time zone, handles summer and winter time	Return deadline “Nov 19 at 6:00 pm in Berlin”
`Temporal.PlainDate`	Calendar date without time and without time zone	Birthday, day of borrowing, holiday
`Temporal.PlainTime`	Wall-clock time without a date	Closing time “18:00”
`Temporal.PlainDateTime`	Date and time without a time zone	Form input before the time zone is known
`Temporal.Duration`	Length of time in years, months, days, hours …	Loan period, gap between two appointments

There are also PlainYearMonth (for a billing month, say), PlainMonthDay (recurring anniversaries) and Temporal.Now for the current time in various forms.

Rule of thumb for choosing a Temporal type

The rule of thumb for choosing a type

For every value I ask myself one single question: do I need to know exactly when this happens in the world? If yes, I need an Instant or a ZonedDateTime. A return deadline belongs in this group, because at 6:01 pm in Berlin it has expired, no matter where the server is. If the answer is no, a plain type is enough. A birthday is on May 3, whatever time zone you happen to be in.

A mistake I see often: deadlines get stored as PlainDateTime because it looks so simple. Then exactly the information you later need for comparisons is missing. PlainDateTime is meant for intermediate steps, for example a form before it is clear which time zone the appointment takes place in.

Setting up the Temporal API in TypeScript

Before you start, a quick look at support. Temporal has reached stage 4 in the TC39 process, the standards committee for JavaScript, which means it is fully specified. Firefox has shipped the API since version 139, Chrome since version 144 and Node.js since version 26. According to the proposal repository, Safari is still missing. TypeScript has included the matching types since version 6.0.

Prerequisites

Node.js 26 locally (for native Temporal support) or Node.js 22/24 with a polyfill
TypeScript 6.0 or later; the example was tested with TypeScript 7.0.2
For deployment: an AWS account and the Serverless Framework v4 (npm i -g serverless)
Basic knowledge of Lambda and DynamoDB helps but isn’t required

Lambda runtime and polyfill

On Lambda, nodejs26.x is still a public preview, and AWS plans the regular launch for November 2026. Preview runtimes come without the Lambda SLA and are not intended for production use. Until then, use nodejs24.x and load the temporal-polyfill package (MIT license). Its entry point temporal-polyfill/global installs Temporal globally only if the runtime doesn’t already provide it. I checked this in the package’s source code: on Node.js 26 the import simply does nothing. So later you can switch the runtime without touching a single line of code.

Configuring TypeScript

You enable the types via the lib option. Either take all of esnext or only the esnext.temporal part. I prefer the more granular option because it makes clear which new features the project actually uses.

{
  "compilerOptions": {
    "target": "es2024",
    "lib": ["es2024", "esnext.temporal"],
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "strict": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "types": ["node"],
    "skipLibCheck": true
  },
  "include": ["src", "test"]
}

allowImportingTsExtensions and erasableSyntaxOnly let Node.js run the TypeScript files directly. We will use that for the tests in a moment, without any build step.

Step by step: loan deadlines for a library

Our example is a fictional city library with clear rules. A book may be borrowed for 21 days. If the last day falls on a Sunday or a holiday, the return moves to the next opening day. You can return books until 6:00 pm Berlin time. Two days before the deadline a reminder goes out at 9:00 am, and every overdue day costs 50 cents, up to a maximum of 10 euros.

Step 1: Create the project

mkdir temporal-library-loans && cd temporal-library-loans
npm init -y
npm pkg set type=module
npm i temporal-polyfill @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
npm i -D typescript @types/node @types/aws-lambda
mkdir src test

Then create the tsconfig.json shown above. Next comes a tiny file that loads the polyfill when needed:

// src/temporal.ts
// Loads the polyfill only if the runtime has no native Temporal
// (e.g. nodejs24.x on Lambda). On Node.js 26 this does nothing.
import "temporal-polyfill/global";

Step 2: The deadline logic as pure functions

The rules go into a file without any AWS dependencies. That makes them easy to test and independent of where the code runs later.

// src/loan-rules.ts
import "./temporal.ts";

export const LIBRARY_ZONE = "Europe/Berlin";
export const LOAN_DAYS = 21;
export const CLOSING_TIME = Temporal.PlainTime.from("18:00");
export const FEE_PER_DAY_CENTS = 50;
export const MAX_FEE_CENTS = 1000;

// Holidays when the library is closed (fictional selection)
export const HOLIDAYS = new Set(["2026-12-25", "2026-12-26", "2027-01-01"]);

function isClosed(date: Temporal.PlainDate): boolean {
  return date.dayOfWeek === 7 || HOLIDAYS.has(date.toString());
}

// Due date: day of borrowing + 21 days; on a Sunday or holiday, the next opening day
export function dueDate(borrowedOn: Temporal.PlainDate): Temporal.PlainDate {
  let due = borrowedOn.add({ days: LOAN_DAYS });
  while (isClosed(due)) {
    due = due.add({ days: 1 });
  }
  return due;
}

// Exact deadline: due date at 6:00 pm Berlin time
export function returnDeadline(due: Temporal.PlainDate): Temporal.ZonedDateTime {
  return due.toZonedDateTime({ timeZone: LIBRARY_ZONE, plainTime: CLOSING_TIME });
}

// Reminder two calendar days earlier at 9:00 am – wall-clock time, even across DST changes
export function reminderAt(deadline: Temporal.ZonedDateTime): Temporal.ZonedDateTime {
  return deadline.subtract({ days: 2 }).with({ hour: 9, minute: 0 });
}

// Overdue days: calendar days between due date and today (never negative)
export function overdueDays(due: Temporal.PlainDate, today: Temporal.PlainDate): number {
  const days = due.until(today, { largestUnit: "days" }).days;
  return Math.max(0, days);
}

export function lateFeeCents(due: Temporal.PlainDate, today: Temporal.PlainDate): number {
  return Math.min(overdueDays(due, today) * FEE_PER_DAY_CENTS, MAX_FEE_CENTS);
}

// "Today" from the library's point of view – not from the Lambda server's (UTC)
export function libraryToday(now: Temporal.Instant): Temporal.PlainDate {
  return now.toZonedDateTimeISO(LIBRARY_ZONE).toPlainDate();
}

A few spots deserve a second look. The due date is a PlainDate, because “21 days later” is purely a calendar question. dayOfWeek follows the ISO standard from 1 (Monday) to 7 (Sunday), so the Sunday-is-zero confusion of Date is finally gone. Only in returnDeadline do time and time zone come in, turning the calendar day into an actual instant.

For the reminder, we deliberately calculate in calendar days and then set the time with with(). If the DST change falls between reminder and deadline, it still stays at 9:00 am wall-clock time. That is exactly what people expect when a reminder is supposed to arrive “at nine in the morning”.

The libraryToday function looks harmless but matters a lot. It receives an Instant and converts it into the library’s time zone. As a result, “today” is always Berlin’s today, even though Lambda runs in UTC. And because the instant comes from outside, you can simulate any time you like in tests.

Step 3: Storing Temporal values in DynamoDB

DynamoDB has no date type. So you have to decide in which form to store the values, and that decision matters more than it seems. My suggestion:

Plain calendar dates as ISO strings like 2026-11-19. They are readable and sort lexicographically.
Instants as UTC strings like 2026-11-19T17:00:00Z. That way comparisons and range queries on a sort key work.
The time zone separately as an IANA name like Europe/Berlin, so you can restore local time for display.
For DynamoDB TTL, an additional number with epoch seconds, because TTL ignores anything that isn’t a Number attribute.

// src/storage.ts
import "./temporal.ts";

export interface Loan {
  loanId: string;
  bookId: string;
  memberId: string;
  borrowedOn: Temporal.PlainDate;
  due: Temporal.PlainDate;
  deadline: Temporal.ZonedDateTime;
}

export interface LoanItem {
  pk: string;
  bookId: string;
  memberId: string;
  borrowedOn: string;     // "2026-10-29" – plain date, no time
  dueDate: string;        // "2026-11-19"
  deadlineAt: string;     // "2026-11-19T17:00:00Z" – UTC, sortable
  timeZone: string;       // "Europe/Berlin" – for display
  expiresAt: number;      // epoch seconds for DynamoDB TTL
}

const KEEP_AFTER_DEADLINE = { days: 180 };

export function toItem(loan: Loan): LoanItem {
  return {
    pk: `LOAN#${loan.loanId}`,
    bookId: loan.bookId,
    memberId: loan.memberId,
    borrowedOn: loan.borrowedOn.toString(),
    dueDate: loan.due.toString(),
    deadlineAt: loan.deadline.toInstant().toString(),
    timeZone: loan.deadline.timeZoneId,
    expiresAt: Math.floor(loan.deadline.add(KEEP_AFTER_DEADLINE).epochMilliseconds / 1000),
  };
}

export function fromItem(item: LoanItem): Loan {
  return {
    loanId: item.pk.replace("LOAN#", ""),
    bookId: item.bookId,
    memberId: item.memberId,
    borrowedOn: Temporal.PlainDate.from(item.borrowedOn),
    due: Temporal.PlainDate.from(item.dueDate),
    deadline: Temporal.Instant.from(item.deadlineAt).toZonedDateTimeISO(item.timeZone),
  };
}

Why not just store the string of a ZonedDateTime, i.e. 2026-11-19T18:00:00+01:00[Europe/Berlin]? It does contain everything, but it doesn’t sort reliably once values with different offsets end up in the same column. The UTC instant doesn’t have that problem. You can read more about TTL and expiry dates in my post DynamoDB TTL: build seat holds that expire.

Step 4: Lambda handler and serverless.yml

The handler is intentionally lean. It reads the book and member from the request, calculates date, deadline and reminder and writes the record to DynamoDB.

// src/handler.ts
import { randomUUID } from "node:crypto";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";
import type { APIGatewayProxyEventV2, APIGatewayProxyResultV2 } from "aws-lambda";
import { dueDate, libraryToday, reminderAt, returnDeadline } from "./loan-rules.ts";
import { toItem, type Loan } from "./storage.ts";

const db = DynamoDBDocumentClient.from(new DynamoDBClient({}));
const TABLE = process.env.LOANS_TABLE ?? "";

export async function createLoan(event: APIGatewayProxyEventV2): Promise<APIGatewayProxyResultV2> {
  const body = JSON.parse(event.body ?? "{}") as { bookId?: string; memberId?: string };
  if (!body.bookId || !body.memberId) {
    return { statusCode: 400, body: JSON.stringify({ message: "bookId and memberId are required" }) };
  }

  const borrowedOn = libraryToday(Temporal.Now.instant());
  const due = dueDate(borrowedOn);
  const deadline = returnDeadline(due);
  const loan: Loan = {
    loanId: randomUUID(),
    bookId: body.bookId,
    memberId: body.memberId,
    borrowedOn,
    due,
    deadline,
  };

  await db.send(new PutCommand({ TableName: TABLE, Item: toItem(loan) }));

  return {
    statusCode: 201,
    body: JSON.stringify({
      loanId: loan.loanId,
      dueDate: due.toString(),
      deadline: deadline.toString(),
      reminder: reminderAt(deadline).toString(),
    }),
  };
}

🎬 Flow of a book loan with Temporal – this animated diagram only runs on my site: watch it on sascha-ms.de

For the infrastructure I am using the Serverless Framework here. Since version 4 it builds TypeScript itself with esbuild, so no extra build configuration is needed.

# serverless.yml
service: library-loans
frameworkVersion: "4"

provider:
  name: aws
  runtime: nodejs24.x        # switch to nodejs26.x once it is GA
  region: eu-central-1
  architecture: arm64
  memorySize: 256
  environment:
    LOANS_TABLE: ${self:service}-${sls:stage}-loans
    TZ: UTC                  # Lambda default; library time comes from the code
  iam:
    role:
      statements:
        - Effect: Allow
          Action:
            - dynamodb:PutItem
          Resource:
            - !GetAtt LoansTable.Arn

functions:
  createLoan:
    handler: src/handler.createLoan
    events:
      - httpApi:
          path: /loans
          method: post

resources:
  Resources:
    LoansTable:
      Type: AWS::DynamoDB::Table
      Properties:
        TableName: ${self:service}-${sls:stage}-loans
        BillingMode: PAY_PER_REQUEST
        AttributeDefinitions:
          - AttributeName: pk
            AttributeType: S
        KeySchema:
          - AttributeName: pk
            KeyType: HASH
        TimeToLiveSpecification:
          AttributeName: expiresAt
          Enabled: true

The IAM role may only call PutItem on exactly this table. The handler needs nothing more. Deploy and try it out:

serverless deploy
curl -X POST "https://<your-api-id>.execute-api.eu-central-1.amazonaws.com/loans" \
  -H "Content-Type: application/json" \
  -d '{"bookId":"book-42","memberId":"reader-7"}'

If you borrow on October 29, 2026, the response looks roughly like this (the loanId will of course differ):

{
  "loanId": "3f2c9a4e-8b1d-4c57-9e0a-5d6f7a8b9c01",
  "dueDate": "2026-11-19",
  "deadline": "2026-11-19T18:00:00+01:00[Europe/Berlin]",
  "reminder": "2026-11-17T09:00:00+01:00[Europe/Berlin]"
}

Step 5: Testing across the DST change

Now comes the part I consider most important for date logic. Tests with “today plus three days” are almost always green and prove little. They only become meaningful with fixed dates around the DST change, holidays and the day boundary between UTC and Berlin.

// test/loan-rules.test.ts
import { test } from "node:test";
import assert from "node:assert/strict";
import { dueDate, lateFeeCents, libraryToday, overdueDays, reminderAt, returnDeadline } from "../src/loan-rules.ts";

const day = (s: string) => Temporal.PlainDate.from(s);

test("due date is 21 days after borrowing", () => {
  assert.equal(dueDate(day("2026-10-29")).toString(), "2026-11-19");
});

test("holidays and Sundays move to the next opening day", () => {
  // Dec 25 holiday, Dec 26 holiday, Dec 27 Sunday
  assert.equal(dueDate(day("2026-12-04")).toString(), "2026-12-28");
});

test("deadline stays at 6:00 pm Berlin time, even after the DST change", () => {
  const deadline = returnDeadline(day("2026-10-26"));
  assert.equal(deadline.toString(), "2026-10-26T18:00:00+01:00[Europe/Berlin]");
  assert.equal(deadline.toInstant().toString(), "2026-10-26T17:00:00Z");
});

test("reminder at 9:00 am wall-clock time across the DST change", () => {
  const reminder = reminderAt(returnDeadline(day("2026-10-26")));
  assert.equal(reminder.toString(), "2026-10-24T09:00:00+02:00[Europe/Berlin]");
});

test("overdue days and capped fee", () => {
  assert.equal(overdueDays(day("2026-11-19"), day("2026-11-23")), 4);
  assert.equal(overdueDays(day("2026-11-19"), day("2026-11-10")), 0);
  assert.equal(lateFeeCents(day("2026-11-19"), day("2026-11-23")), 200);
  assert.equal(lateFeeCents(day("2026-11-19"), day("2026-12-31")), 1000);
});

test("“today” is based on Berlin, not UTC", () => {
  // 23:30 UTC is already the next day in Berlin
  assert.equal(libraryToday(Temporal.Instant.from("2026-10-29T23:30:00Z")).toString(), "2026-10-30");
});

You can run the tests directly with Node.js, without a compile step:

npx tsc --noEmit
node --test test/*.test.ts

Expected result: all tests pass. I ran them on Node.js 26.13 with native Temporal and on Node.js 22 with the polyfill, both times with identical results. The repository also contains a second test for the round trip through DynamoDB and the conversion from Date, which I leave out here to save space.

Summer and winter time: what Temporal decides behind the scenes

Twice a year there are times in Berlin that are ambiguous. In spring an hour is missing: on March 28, 2027 the clock jumps from 2:00 am to 3:00 am, so “2:30 am” doesn’t exist that day. In autumn an hour happens twice: on October 25, 2026, 2:30 am occurs once in summer time and once in winter time.

Temporal solves this with the disambiguation option. The default value compatible behaves like Date: inside the gap the time is pushed forward, and in the repeated hour the earlier one wins. With earlier or later you pick a variant on purpose, and with reject Temporal throws a RangeError.

// Spring gap: 2:30 am does not exist
Temporal.ZonedDateTime.from("2027-03-28T02:30[Europe/Berlin]").toString();
// 2027-03-28T03:30:00+02:00[Europe/Berlin]

// Repeated hour in autumn: deliberately pick the second 2:30 am
Temporal.PlainDateTime.from("2026-10-25T02:30")
  .toZonedDateTime("Europe/Berlin", { disambiguation: "later" })
  .toString();
// 2026-10-25T02:30:00+01:00[Europe/Berlin]

// Often the best choice for booking systems: an error beats a silent shift
Temporal.PlainDateTime.from("2027-03-28T02:30")
  .toZonedDateTime("Europe/Berlin", { disambiguation: "reject" }); // RangeError

Something similar applies to month arithmetic. January 31 plus one month gives February 28 with the default overflow: "constrain". If you prefer an error, pass { overflow: "reject" }. For subscriptions and contract terms this is a business decision that you should clarify with the domain experts instead of leaving it to chance.

Migrating from Date and date-fns

Hardly any project can switch everything overnight. It doesn’t have to. I would use Temporal first in new business logic and convert at the edges, wherever older libraries, ORMs or SDKs still expect or return Date.

// src/legacy.ts
import "./temporal.ts";

// Existing code still returns Date objects? This converts them without loss.
export function fromLegacyDate(value: Date): Temporal.Instant {
  return Temporal.Instant.fromEpochMilliseconds(value.getTime());
}

// For libraries that still expect Date (e.g. older SDKs)
export function toLegacyDate(value: Temporal.Instant): Date {
  return new Date(value.epochMilliseconds);
}

Going through epoch milliseconds is lossless, because Date only knows milliseconds anyway. Native runtimes and the polyfill also offer Date.prototype.toTemporalInstant(). I still prefer the explicit function, because it shows in the code where the old world ends.

With date-fns, Day.js or Luxon it pays to look at what the library is actually used for. Often it is a handful of functions like addDays, differenceInDays or format. Temporal replaces the first two directly with add() and until(). For formatting there is toLocaleString(), which uses Intl.DateTimeFormat internally. Temporal.PlainDate.from("2026-11-19").toLocaleString("en-US", { dateStyle: "full" }), for example, returns “Thursday, November 19, 2026”. Running both side by side is fine for a transition period. The only important thing is that a function works either with Temporal or with Date, not with both.

Common mistakes with the Temporal API in TypeScript

A few pitfalls kept coming up while I was trying things out.

Comparing with === or <: Two Temporal objects with the same value are still different objects. Use equals() or the static compare() method. Comparing with < deliberately throws a TypeError.
Temporal.Now deep inside business logic: Then you can’t control time in tests. Get the current time at the edge, for example in the handler, and pass it on as a parameter.
JSON there, but not back: JSON.stringify turns Temporal objects into strings. When reading them back, you have to convert them with from() yourself, or you keep calculating with strings.
structuredClone and workers: Temporal objects can’t be structured-cloned, and Node.js throws a DataCloneError. Pass strings and rebuild the objects on the other side.
Storing an offset instead of a time zone: +01:00 is not a time zone. In summer, Berlin uses +02:00. If you only know the offset, you can’t calculate correctly into the future.

Cost, performance and security

The polyfill has a price, but it is modest. In my example, the minified handler including the polyfill weighs about 60 KB, not counting the AWS SDK, which is part of the runtime. For a Lambda cold start that hardly matters. Once nodejs26.x is generally available, you can remove the polyfill and save those bytes entirely.

DynamoDB TTL costs nothing extra. Expired items are deleted without consuming write capacity, though not immediately: according to AWS, typically within a few days. Queries should therefore filter out expired items themselves. With global tables, however, the replicated deletes in other regions do consume write capacity.

Two notes on security. Always validate date values from requests with from() inside a try block, because invalid input throws a RangeError. And don’t accept time zones from requests unchecked; compare them against a list of allowed zones. For scheduled reminders, EventBridge Scheduler is a good fit, since it understands cron expressions with a time zone. My EventBridge cron explainer shows how such expressions are built.

My take

I consider Temporal one of the most useful additions JavaScript has received in recent years. You could build correct code with Date, too. What makes Temporal valuable is that it forces the right questions. If you have to choose between PlainDate and ZonedDateTime, you automatically think about what a value means in business terms.

At the same time, I wouldn’t rebuild everything at once. Existing code with date-fns that has been running reliably for years is not an emergency. New business logic, though, I would write with Temporal starting now, on Lambda with the polyfill for the time being. For frontends that also serve Safari, the polyfill remains mandatory for a while anyway. One point where I stay skeptical: the API is large. Teams should agree on a few types and clear storage formats, otherwise you quickly end up with a new kind of sprawl, just with more modern names.

FAQ

Can I use the Temporal API in production already?

Yes. Temporal is fully standardized and available without a flag in Node.js 26, Chrome and Firefox. For Safari and older Node versions such as nodejs24.x on Lambda, use a polyfill like temporal-polyfill.

Which TypeScript version do I need for Temporal?

The types are built in from TypeScript 6.0. You enable them with "lib": ["esnext"], with "target": "esnext" or specifically with esnext.temporal.

What is the difference between Instant and ZonedDateTime?

Both describe an exact point in time. An Instant, however, has no time zone and therefore no calendar. ZonedDateTime also knows the time zone in which the instant is viewed, so it can calculate correctly with days, months and DST changes.

Does Temporal replace date-fns, Luxon or Day.js?

For arithmetic, comparisons and time zones, in many cases yes. For formatting, Temporal uses Intl.DateTimeFormat. Special features like relative times (“3 days ago”) are covered by Intl.RelativeTimeFormat or still by a library.

Your next step

Find a place in your project where a deadline or appointment is calculated with Date today, and write a test for October 25 or March 28. If it passes, great. If not, you have found your first candidate for Temporal.

How do you handle time zones in your Lambda functions so far: everything in UTC with conversion in the frontend, or do you already calculate with local time in the backend? Let me know in the comments.

Time zones matter not only for deadlines but also for triggering jobs. I show how to start cron jobs reliably at German local time in EventBridge Scheduler time zone: cron at local time.

Sources

This post was created with AI assistance.

👉 Next step: Curious what your own Lambda functions cost? Try my Lambda cost calculator – it runs right in your browser.

Originally published on sascha-ms.de. More articles on serverless, AI in everyday development and leading tech teams: sascha-ms.de/en

Node.js 26 LTS: planning the Lambda upgrade

Sascha Mirow-Stanitzok — Sun, 01 Nov 2026 16:54:03 +0000

Node.js 26 LTS has been official since October 28, 2026, under the codename “Lithium”. For me, an LTS switch like this is always the moment to stop eyeing the next release and write an upgrade plan instead. If you only touch your Lambda functions once the deprecation email from AWS lands in your inbox, you work under time pressure. And time pressure is a pretty bad advisor for runtime upgrades.

On AWS Lambda, the nodejs26.x runtime is already available as a public preview, and according to the documentation AWS is targeting general availability for November 2026. That window is valuable: you can test today without having to switch production today. I will show you what Node.js 26 brings, what breaks when you move from Node.js 22 or 24, and how a small probe function for a fictional bike rental tells you what the new Lambda runtime can really do.

In short

Node.js 26 became LTS on October 28, 2026 and receives updates until the end of April 2029, while nodejs26.x on Lambda is still a preview with a planned launch in November 2026. The most useful addition for everyday work is the Temporal API for dates and times. The biggest pitfall: what works under Node 26 on your laptop is not necessarily enabled the same way in the Lambda runtime, so check features there directly instead of assuming them.

What you will learn in this article

What Node.js 26 LTS means for your support timeline on Lambda
Which additions such as Temporal and Map.getOrInsert you can use right away
Which changes can break when you upgrade from Node.js 22 or 24
How to test nodejs26.x next to nodejs24.x with AWS CDK
How to find every Node runtime in your AWS account

What Node.js 26 LTS means for your timeline

LTS stands for Long Term Support: a version receives security and bug fixes over a long period, and new features only arrive cautiously. Release 26.13.0, which officially starts Node.js 26 LTS, is purely formal. According to the release notes, it only switches metadata such as process.release to LTS and contains nothing else beyond 26.12.1. Updates for Node.js 26 LTS continue until the end of April 2029.

The Node.js project is also changing its rhythm. Until now, only even-numbered versions became LTS, while odd ones such as Node.js 25 were done after six months (25 reached EOL, or “end of life”, at the end of March 2026). Starting with Node.js 27, there will be one major version per year, and each of them becomes LTS after its six-month Current phase. For teams, that means fewer versions and a predictable cadence.

Here is where Lambda stands at the end of October 2026:

Runtime	Node.js line	Status on Lambda
`nodejs22.x`	LTS “Jod”	Deprecated on Apr 30, 2027, updates blocked from Aug 31, 2027
`nodejs24.x`	LTS “Krypton”	Deprecated on Apr 30, 2028
`nodejs26.x`	LTS “Lithium”	Public preview, general availability planned for November 2026

For many teams, the date that matters most is the end of nodejs22.x in April 2027.

My take: for many teams, the real deadline is not the launch of Node.js 26 but the deprecation of nodejs22.x. That leaves roughly six months. If you plan now, you can fit the upgrade into your normal sprint cadence.

Node.js 26 LTS features you will notice day to day

Coming from Node.js 24, you get not only the changes in Node.js 26 LTS but also everything from Node.js 25. That intermediate version was never LTS, so many teams skipped it. A few points stand out for daily work.

Temporal: dates and times without the headache

Node.js 26 LTS ships the Temporal API enabled by default, no flag required. Temporal is the new standard for dates and times in JavaScript and fixes the weaknesses of Date: months that start at 0, no real time zone arithmetic, and objects you can mutate by accident. Instead, you get clear types. Temporal.Instant is an exact point in time, Temporal.ZonedDateTime is a point in time in a specific time zone, and Temporal.PlainDate is a plain calendar date.

const pickup = Temporal.ZonedDateTime.from("2026-10-24T10:00[Europe/Berlin]");
const due = pickup.add({ days: 2 });

console.log(due.toString());
// 2026-10-26T10:00:00+01:00[Europe/Berlin]  (same wall-clock time, even though the DST change happens in between)

We will use exactly this example in the probe function later. With Date and “plus 48 hours”, you end up at 9 a.m. instead of 10 a.m. on October 26, because the clocks go back during the night before October 25. I cover how to use Temporal day to day for deadlines, time zones and DynamoDB in detail in Temporal API in TypeScript: deadlines and time zones.

Small helpers: getOrInsert, Iterator.concat and Base64

V8 14.6 adds two small but pleasant functions. Map.prototype.getOrInsert() and getOrInsertComputed() read a value or create it if it is missing. The classic “does this key exist yet?” pattern for grouping shrinks to a single line. Iterator.concat() chains several iterators without building intermediate arrays.

const rentals = [
  { station: "Central Station", bikeId: "city-bike-17" },
  { station: "Old Town", bikeId: "e-bike-03" },
  { station: "Central Station", bikeId: "cargo-bike-02" },
];

const byStation = new Map<string, string[]>();
for (const rental of rentals) {
  byStation.getOrInsert(rental.station, []).push(rental.bikeId);
}
// Map { "Central Station" => ["city-bike-17", "cargo-bike-02"], "Old Town" => ["e-bike-03"] }

Node.js 25 contributed, for example, Uint8Array.fromBase64() and toBase64() (plus hex variants) and a noticeably faster JSON.stringify. In Lambda functions that build lots of JSON responses or encode binary data for API Gateway, that is a nice bonus for free. One observation from my test: with "lib": ["esnext"], TypeScript 7.0.2 already knows the types for Temporal, getOrInsert and fromBase64, but still reports an error for Iterator.concat.

Platform: Undici 8, Web Storage and permissions

Undici, the built-in HTTP client behind fetch, moves to version 8. Since Node.js 25, the Web Storage API is enabled by default, but in Node.js 26 localStorage returns undefined as long as no storage file is configured. Since Node.js 25, the permission model also knows --allow-net, which lets you restrict a process’s network access. On Lambda, that matters more for local tools and CI scripts, because isolation there is handled by IAM and VPC anyway.

What breaks when you move to Node.js 26 LTS

Most projects keep running after the upgrade to Node.js 26 LTS. Still, there are a handful of changes worth checking deliberately before you switch the runtime:

The old internal modules _stream_readable, _stream_writable and their siblings are removed in Node.js 26. Older libraries sometimes still import them directly.
http.Server.prototype.writeHeader() is gone, use writeHead().
Since Node.js 25, fs.F_OK, fs.R_OK, fs.W_OK and fs.X_OK are no longer exported directly from the module. The constants live under fs.constants.
SlowBuffer and assert.CallTracker have reached end of life since Node.js 25.
Corepack is no longer bundled since Node.js 25. If you enable pnpm or Yarn via Corepack, install it separately in CI.
module.register() emits a runtime deprecation warning in Node.js 26, and --experimental-transform-types was removed.
Native addons need a rebuild, because NODE_MODULE_VERSION changes to 147.
Since Node.js 25, the official Linux binaries are linked against libatomic. Slim container images for CI may be missing that package.

On top of that on Lambda: what has applied since nodejs24.x

If you jump from nodejs22.x straight to 26, you also pick up the Lambda-specific changes AWS introduced with nodejs24.x. Callback handlers are no longer supported, context.callbackWaitsForEmptyEventLoop is removed, and so are context.succeed, fail and done. In addition, Lambda no longer waits for pending promises once your handler returns. Anything you still want to finish has to be completed with await first.

// Before: callback handler (no longer works from nodejs24.x)
export const handler = (event, context, callback) => {
  loadBike(event.bikeId)
    .then((bike) => callback(null, bike))
    .catch((err) => callback(err));
};

// After: async handler, every piece of work is awaited
export const handler = async (event: { bikeId: string }) => {
  const bike = await loadBike(event.bikeId);
  await auditLog.write({ action: "lookup", bikeId: bike.id }); // without await this would get lost
  return bike;
};

One more point is easy to miss: Lambda disables experimental Node.js features by default, such as require() of ES modules and automatic module detection. You can turn them back on via NODE_OPTIONS, but AWS covers such cases with neither support nor the SLA.

nodejs26.x on Lambda: the state at the end of October 2026

The nodejs26.x runtime is available as a public preview, both as a ZIP runtime and as the container base image public.ecr.aws/lambda/nodejs:26-preview. Preview means no SLA, no technical support, and breaking changes are possible. It is explicitly not meant for production workloads. AWS names November 2026 as the launch of the stable version, but only as a non-binding estimate.

The feedback issue for the preview on GitHub is revealing. Users report, among other things, that Temporal is missing in the preview and that process.features.require_module is false. These are community observations, not an official AWS statement, and a lot can change before the stable release. I still think the lesson matters: a Lambda runtime is not automatically identical to the Node.js on your machine. So let us check directly in Lambda.

🎬 Probe function on two Lambda runtimes – this animated diagram only runs on my site: watch it on sascha-ms.de

Step by step: testing nodejs26.x next to nodejs24.x

Our example is a fictional bike rental. A function calculates when a rented bike has to be back: same time of day, a given number of days later, in the time zone of the rental station. It also returns a small report on which features the runtime really provides. If Temporal is built in, the function uses it, otherwise a polyfill steps in. A polyfill is a retrofitted implementation of a standard API for environments that do not support it yet.

Prerequisites

Node.js 22 or newer locally (thanks to the polyfill, the tests run without Node.js 26 too)
AWS CLI v2 with credentials for a test or sandbox account
An account bootstrapped with npx cdk bootstrap in your region
A region where nodejs26.x is already selectable. You can see that in the Lambda console when creating a function.

Step 1: create the project

mkdir bike-rental-runtime-check && cd bike-rental-runtime-check
npm init -y
npm install @js-temporal/polyfill@0.5.1
npm install -D typescript@7.0.2 @types/node@26 @types/aws-lambda tsx esbuild aws-cdk-lib@2.275.0 constructs aws-cdk@2.1146.1
mkdir -p bin lib src test

Switch package.json to ES modules and add a few scripts:

{
  "name": "node26-lambda-upgrade",
  "version": "1.0.0",
  "scripts": {
    "typecheck": "tsc --noEmit -p .",
    "test": "node --import tsx --test test/*.test.ts",
    "synth": "cdk synth",
    "deploy": "cdk deploy"
  },
  "license": "MIT",
  "devDependencies": {
    "@types/aws-lambda": "^8.10.164",
    "@types/node": "^26.6.6",
    "aws-cdk": "^2.1146.1",
    "aws-cdk-lib": "^2.275.0",
    "constructs": "^10.8.1",
    "esbuild": "^0.28.2",
    "tsx": "^4.23.15",
    "typescript": "^7.0.2"
  },
  "dependencies": {
    "@js-temporal/polyfill": "^0.5.1"
  },
  "private": true,
  "type": "module"
}

Step 2: configure TypeScript

With "lib": ["esnext"], TypeScript knows the new APIs such as Temporal. noEmit is enough, because esbuild bundles during deployment and tsx runs the tests directly.

// tsconfig.json
{
  "compilerOptions": {
    "target": "es2024",
    "lib": ["esnext"],
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "strict": true,
    "types": ["node"],
    "noEmit": true,
    "skipLibCheck": true
  },
  "include": ["bin", "lib", "src", "test"]
}

Step 3: write the runtime report

The function checks every feature directly instead of inferring it from the version number. That is more reliable, because a runtime can have a feature disabled despite a matching version.

// src/runtime-report.ts
// Reports which runtime features are actually available in the current Node.js environment.

export interface RuntimeReport {
  nodeVersion: string;
  ltsName: string | null;
  temporal: boolean;
  mapGetOrInsert: boolean;
  iteratorConcat: boolean;
  uint8ArrayBase64: boolean;
  requireModule: boolean;
  lambdaRuntime: string | null;
}

export function collectRuntimeReport(env: NodeJS.ProcessEnv = process.env): RuntimeReport {
  const g = globalThis as Record<string, unknown>;
  const iteratorCtor = g.Iterator as { concat?: unknown } | undefined;

  return {
    nodeVersion: process.version,
    ltsName: process.release.lts ?? null,
    temporal: typeof g.Temporal === "object" && g.Temporal !== null,
    mapGetOrInsert: typeof (Map.prototype as { getOrInsert?: unknown }).getOrInsert === "function",
    iteratorConcat: typeof iteratorCtor?.concat === "function",
    uint8ArrayBase64: typeof (Uint8Array as { fromBase64?: unknown }).fromBase64 === "function",
    requireModule: process.features.require_module === true,
    // In Lambda, AWS_EXECUTION_ENV looks like this, for example: AWS_Lambda_nodejs24.x
    lambdaRuntime: env.AWS_EXECUTION_ENV?.replace("AWS_Lambda_", "") ?? null,
  };
}

Step 4: load Temporal with a fallback

// src/temporal.ts
// Uses the built-in Temporal if the runtime provides it, otherwise the polyfill.

export type TemporalApi = typeof Temporal;

export async function loadTemporal(): Promise<{ api: TemporalApi; source: "runtime" | "polyfill" }> {
  const builtIn = (globalThis as { Temporal?: TemporalApi }).Temporal;
  if (builtIn) {
    return { api: builtIn, source: "runtime" };
  }
  const polyfill = await import("@js-temporal/polyfill");
  return { api: polyfill.Temporal as unknown as TemporalApi, source: "polyfill" };
}

The dynamic import ensures that the polyfill is only loaded when it is needed. esbuild still bundles it, which makes the package about 150 KB larger. Once Temporal is reliably available in the stable runtime, you can remove the fallback.

Step 5: the rental logic

// src/rental.ts
// Fictional bike rental: when does a bike have to be back?

import type { TemporalApi } from "./temporal.js";

export interface RentalRequest {
  bikeId: string;
  pickupAt: string; // pickup time as an instant, e.g. "2026-10-24T08:00:00Z"
  days: number; // number of rental days
  timeZone: string; // time zone of the rental station, e.g. "Europe/Berlin"
}

export function validateRental(input: Partial<RentalRequest>): RentalRequest {
  const { bikeId, pickupAt, days, timeZone } = input;
  if (!bikeId || !pickupAt || !timeZone) {
    throw new Error("bikeId, pickupAt and timeZone are required");
  }
  if (typeof days !== "number" || !Number.isInteger(days) || days < 1 || days > 30) {
    throw new Error("days must be an integer between 1 and 30");
  }
  return { bikeId, pickupAt, days, timeZone };
}

// With Temporal, "2 days" means the same wall-clock time two calendar days later, even across a DST change.
export function returnDeadline(T: TemporalApi, req: RentalRequest): string {
  return T.Instant.from(req.pickupAt)
    .toZonedDateTimeISO(req.timeZone)
    .add({ days: req.days })
    .toString({ smallestUnit: "minute" });
}

// The classic Date approach just adds milliseconds. Across a DST change it is off by one hour.
export function naiveReturnDeadline(req: RentalRequest): string {
  const start = new Date(req.pickupAt).getTime();
  return new Date(start + req.days * 24 * 60 * 60 * 1000).toISOString();
}

Step 6: the Lambda handler

// src/handler.ts
// Lambda handler: returns the runtime report and the return deadline for a rental.

import { collectRuntimeReport } from "./runtime-report.js";
import { loadTemporal } from "./temporal.js";
import { naiveReturnDeadline, returnDeadline, validateRental, type RentalRequest } from "./rental.js";

const DEMO_RENTAL: RentalRequest = {
  bikeId: "city-bike-17",
  pickupAt: "2026-10-24T08:00:00Z",
  days: 2,
  timeZone: "Europe/Berlin",
};

// Deliberately async without a callback: since nodejs24.x, Lambda no longer supports callback handlers.
export const handler = async (event: Partial<RentalRequest> = {}) => {
  const rental = validateRental({ ...DEMO_RENTAL, ...event });
  const { api, source } = await loadTemporal();

  return {
    runtime: collectRuntimeReport(),
    temporalSource: source,
    rental: {
      bikeId: rental.bikeId,
      returnAt: returnDeadline(api, rental),
      naiveReturnAtUtc: naiveReturnDeadline(rental),
    },
  };
};

Step 7: tests with the Node test runner

The tests cover the interesting case: a rental across the DST change on October 25, 2026. This shows in black and white why Temporal is worth the switch.

// test/rental.test.ts
import { test } from "node:test";
import assert from "node:assert/strict";
import { loadTemporal } from "../src/temporal.js";
import { naiveReturnDeadline, returnDeadline, validateRental } from "../src/rental.js";

const overDstChange = validateRental({
  bikeId: "city-bike-17",
  pickupAt: "2026-10-24T08:00:00Z", // 10:00 in Berlin (summer time)
  days: 2,
  timeZone: "Europe/Berlin",
});

test("Temporal keeps the wall-clock time across the DST change", async () => {
  const { api } = await loadTemporal();
  assert.equal(returnDeadline(api, overDstChange), "2026-10-26T10:00+01:00[Europe/Berlin]");
});

test("Date arithmetic ends up one hour early after the DST change", () => {
  // 08:00 UTC on Oct 26 is 09:00 winter time in Berlin, not 10:00
  assert.equal(naiveReturnDeadline(overDstChange), "2026-10-26T08:00:00.000Z");
});

test("without a DST change both approaches agree", async () => {
  const { api } = await loadTemporal();
  const normalWeek = { ...overDstChange, pickupAt: "2026-11-02T09:00:00Z" };
  assert.equal(returnDeadline(api, normalWeek), "2026-11-04T10:00+01:00[Europe/Berlin]");
  assert.equal(naiveReturnDeadline(normalWeek), "2026-11-04T09:00:00.000Z");
});

test("invalid rental duration is rejected", () => {
  assert.throws(() => validateRental({ ...overDstChange, days: 0 }), /days must/);
  assert.throws(() => validateRental({ ...overDstChange, days: 1.5 }), /days must/);
});

// test/runtime-report.test.ts
import { test } from "node:test";
import assert from "node:assert/strict";
import { collectRuntimeReport } from "../src/runtime-report.js";
import { handler } from "../src/handler.js";

test("report contains the Node version and detects the Lambda runtime", () => {
  const report = collectRuntimeReport({ AWS_EXECUTION_ENV: "AWS_Lambda_nodejs26.x" });
  assert.match(report.nodeVersion, /^v\d+\./);
  assert.equal(report.lambdaRuntime, "nodejs26.x");
});

test("outside of Lambda, lambdaRuntime is null", () => {
  assert.equal(collectRuntimeReport({}).lambdaRuntime, null);
});

test("handler returns report and return deadline", async () => {
  const result = await handler({ days: 3 });
  assert.equal(result.rental.bikeId, "city-bike-17");
  assert.equal(result.rental.returnAt, "2026-10-27T10:00+01:00[Europe/Berlin]");
  assert.ok(["runtime", "polyfill"].includes(result.temporalSource));
});

Step 8: the CDK stack with two runtimes

The installed version of aws-cdk-lib (2.275.0) does not ship nodejs26.x as a ready-made constant yet. That is not a problem, because new Runtime(...) lets you define any runtime yourself. The stack creates the same function twice. If you have not used AWS CDK with TypeScript before, my introduction Lambda function with CDK and TypeScript will help.

// lib/runtime-check-stack.ts
import * as path from "node:path";
import { CfnOutput, Duration, RemovalPolicy, Stack, type StackProps } from "aws-cdk-lib";
import { Architecture, Runtime, RuntimeFamily } from "aws-cdk-lib/aws-lambda";
import { NodejsFunction, OutputFormat } from "aws-cdk-lib/aws-lambda-nodejs";
import { LogGroup, RetentionDays } from "aws-cdk-lib/aws-logs";
import type { Construct } from "constructs";

// aws-cdk-lib does not ship a constant for nodejs26.x yet, so we define it ourselves.
const NODEJS_26_PREVIEW = new Runtime("nodejs26.x", RuntimeFamily.NODEJS, { supportsInlineCode: true });

export class RuntimeCheckStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const variants = [
      { name: "Node24", runtime: Runtime.NODEJS_24_X, target: "node24" },
      { name: "Node26", runtime: NODEJS_26_PREVIEW, target: "node26" },
    ];

    for (const variant of variants) {
      const logGroup = new LogGroup(this, `${variant.name}Logs`, {
        retention: RetentionDays.ONE_WEEK,
        removalPolicy: RemovalPolicy.DESTROY,
      });

      const fn = new NodejsFunction(this, `RentalCheck${variant.name}`, {
        entry: path.join(import.meta.dirname, "../src/handler.ts"),
        handler: "handler",
        runtime: variant.runtime,
        architecture: Architecture.ARM_64,
        memorySize: 256,
        timeout: Duration.seconds(10),
        logGroup,
        bundling: {
          format: OutputFormat.ESM,
          target: variant.target,
          minify: true,
          sourceMap: true,
          // esbuild needs a require function in the ESM bundle for CommonJS dependencies
          banner: "import { createRequire } from 'module'; const require = createRequire(import.meta.url);",
        },
        environment: {
          NODE_OPTIONS: "--enable-source-maps",
        },
      });

      new CfnOutput(this, `${variant.name}FunctionName`, { value: fn.functionName });
    }
  }
}

// bin/app.ts
import { App } from "aws-cdk-lib";
import { RuntimeCheckStack } from "../lib/runtime-check-stack.js";

const app = new App();
new RuntimeCheckStack(app, "BikeRentalRuntimeCheck", {
  env: { region: process.env.CDK_DEFAULT_REGION ?? "eu-central-1" },
});

// cdk.json
{
  "app": "npx tsx bin/app.ts"
}

Step 9: check, deploy and compare

npm run typecheck
npm test
npx cdk synth
npx cdk deploy

After the deployment, CDK prints both function names. Call both with the same request and compare the responses:

aws lambda invoke --function-name <Node24FunctionName> \
  --cli-binary-format raw-in-base64-out --payload '{"days":2}' node24.json
aws lambda invoke --function-name <Node26FunctionName> \
  --cli-binary-format raw-in-base64-out --payload '{"days":2}' node26.json
diff <(jq .runtime node24.json) <(jq .runtime node26.json)

This is the response when I call the bundled package locally under Node.js 22. Under nodejs26.x you expect a 26.x version, and exactly this report tells you which features are true there:

{
  "runtime": {
    "nodeVersion": "v22.23.4",
    "ltsName": "Jod",
    "temporal": false,
    "mapGetOrInsert": false,
    "iteratorConcat": false,
    "uint8ArrayBase64": false,
    "requireModule": true,
    "lambdaRuntime": "nodejs24.x"
  },
  "temporalSource": "polyfill",
  "rental": {
    "bikeId": "city-bike-17",
    "returnAt": "2026-10-26T10:00+01:00[Europe/Berlin]",
    "naiveReturnAtUtc": "2026-10-26T08:00:00.000Z"
  }
}

The rental field is what matters: the Temporal calculation returns 10 a.m., while the naive Date calculation lands at 9 a.m. local time. On both runtimes, returnAt has to be identical, no matter whether Temporal is built in or the polyfill does the math.

Common mistakes

Runtime rejected: if your region does not offer the preview yet, the deployment fails. For the test, switch to a region where nodejs26.x is selectable in the console.
“Dynamic require … is not supported”: this message appears when an ESM bundle contains a CommonJS dependency. The banner with createRequire in the stack prevents it.
Callback handlers: old code with (event, context, callback) no longer works from nodejs24.x. Switch to async first.
Green locally, different in Lambda: your tests may run with the polyfill locally and with built-in Temporal in Lambda, or the other way round. That is exactly why the report checks every feature in the real runtime.

Cost and security

Two small 256 MB functions that you call a few times cost practically nothing and usually stay within the free tier. With the Lambda cost calculator you can do the math for your real load profiles. Logs are deleted after one week, and npx cdk destroy removes everything again. Do not process real customer data in the preview runtime, since there is neither an SLA nor support for it.

Upgrade checklist for your team

Find the Node runtimes in your account

Before you plan, you need a list. This command shows every function with a Node runtime per region:

for region in eu-central-1 eu-west-1; do
  aws lambda list-functions --region "$region" \
    --query "Functions[?starts_with(Runtime, 'nodejs')].[FunctionName, Runtime]" \
    --output text | sed "s/^/$region\t/"
done

Update TypeScript, bundler and CI

Bump @types/node to version 26, set the matching target in esbuild or on NodejsFunction, and add a Node.js 26 entry to your CI test matrix. Rebuild native addons. And if you use pnpm or Yarn via Corepack, install Corepack explicitly in the pipeline, since it is no longer bundled.

Roll out gradually

Once nodejs26.x is generally available, do not switch all functions at once. I would start with non-critical functions and use an alias with weighted routing to send only part of the traffic to the new version. New runtimes often have somewhat longer cold starts at launch, so keep an eye on error rate and init duration. How to build alarms and dashboards for that is covered in Monitoring Lambda with CDK.

My take

Testing: yes, now. Production on the preview: no. That is my position in a nutshell. The preview is a gift, because you find the surprises while nobody is rushing you yet. If you still run on nodejs22.x today, though, I would not wait for November. The move to 24 brings the biggest Lambda-specific breaks, namely callback handlers and promises that are not awaited. Those affect 26 just the same. Once that is done, the step from 24 to Node.js 26 LTS is small in most projects.

Temporal is what I am looking forward to most. I would rather not count how many time zone and daylight saving bugs I have seen in my career. At the same time, the preview shows that Lambda runtimes are deliberately more conservative than upstream Node.js. For stability, I think that is right, but it can catch you off guard. So my advice: check features in the runtime where your code will actually run. And while you are at it, take a look at your patch routine, because security updates like the one for the Node.js vulnerability CVE-2026-111497 arrive regularly for LTS versions too.

By the way, I like the new annual cadence starting with Node.js 27. A team can schedule one LTS upgrade per year instead of debating every time which version to skip.

FAQ

When will Node.js 26 be generally available on AWS Lambda?

AWS names November 2026 as the planned launch for nodejs26.x, explicitly as a non-binding estimate. Until then, the runtime is a public preview without SLA or support.

How long is Node.js 26 LTS supported?

According to the Node.js project, the 26.x line receives updates until the end of April 2029. When AWS will deprecate the Lambda runtime has not been announced yet.

Can I already use Temporal in Lambda?

Yes, via a polyfill such as @js-temporal/polyfill on any Node runtime. Whether Temporal is built in and enabled in nodejs26.x is best checked with feature detection as in the example.

Do I have to upgrade from Node.js 22 to 24 first?

No, you can go straight to 26. But then you have to handle all changes from 24 and 26 at once. Since nodejs22.x is deprecated in April 2027, going through 24 now is often the more relaxed path.

Your next step

Run the command from the checklist today and count how many functions still run on nodejs22.x. Then deploy the probe function to a sandbox account and check in the report what Node.js 26 LTS really brings in nodejs26.x. I would like to know: which Node runtime are your Lambdas on right now, and what slows you down most when upgrading? Let me know in the comments.

Sources

Node.js blog: Node.js 26.13.0 (LTS), Oct 28, 2026
Node.js blog: Node.js 26.0.0 (Current), May 5, 2026
Node.js blog: Node.js 25.0.0 (Current), Oct 15, 2025
Node.js: releases and release schedule
AWS Lambda Developer Guide: Lambda runtimes
GitHub: feedback issue for the Node.js 26 preview runtime
AWS Compute Blog: Node.js 24 runtime now available in AWS Lambda
Tested with Node.js 22.23, TypeScript 7.0.2 (tsc --noEmit), aws-cdk-lib 2.275.0 (cdk synth), @js-temporal/polyfill 0.5.1 and the Node test runner (7 tests). A deployment to AWS and a run under Node.js 26 were not possible in my test environment.

This post was created with AI assistance.

👉 Next step: Curious what your own Lambda functions cost? Try my Lambda cost calculator – it runs right in your browser.

Originally published on sascha-ms.de. More articles on serverless, AI in everyday development and leading tech teams: sascha-ms.de/en

GitHub Actions lockfile: pin your workflows safely

Sascha Mirow-Stanitzok — Sun, 01 Nov 2026 16:05:54 +0000

A GitHub Actions lockfile is something I have missed for a long time. With npm, Maven or Go it has been normal for years that exactly the version someone reviewed is the one that runs. In workflows, on the other hand, you would find uses: someone/something@v3, and which code sat behind that tag was only decided when the job started. Since October 28, 2026, workflow lockfiles are generally available, and with them you can finally close this gap without unreadable walls of SHAs.

In this article we set up the lockfile step by step in a sample repository (a fictional online bookshop), build a check for pull requests that highlights suspicious changes, and look at how to introduce the mandatory policy in your team without seeing every pipeline turn red on Monday morning.

In short

The new lockfile .github/workflows/actions.lock records the commit and the repository ID for every action and its transitive dependencies, so moved tags can no longer bring unknown code into your pipeline. You create and verify it with the CLI extension gh actions-lock, and Dependabot keeps it up to date. The biggest pitfall are tag-based allowlists for actions: they stop matching after the switch.

What you will learn in this article

Which problem the GitHub Actions lockfile solves and which it does not
How to install gh actions-lock and generate your first lockfile
How CI, Dependabot and CODEOWNERS keep the lockfile current and reviewed
How a small TypeScript tool flags suspicious lockfile changes in a PR
How to roll out the “Require lockfile” policy without outages

Why tags in workflows are a risk

A Git tag is a pointer. Anyone with write access to a repository can move it to a different commit. That is exactly what makes @v3 convenient, because maintainers move the major tag forward with every patch release. At the same time it is the weak spot: if an attacker takes over a maintainer account or a token with write access, v3 may point tomorrow to code nobody on your team has ever seen. Your workflow loads it anyway, with access to secrets, tokens and build artifacts.

The classic countermeasure is SHA pinning directly in the workflow, i.e. uses: actions/checkout@<40-character hash>. It works, but it is tedious to read and only protects the first level. If a composite action calls further actions by tag, you are unprotected again at that point. In addition, a hash does not answer whether the repository behind the name is still the same one, for example after a rename when someone registers the old name again.

What a lockfile changes here

The lockfile separates readability from security. Your workflow keeps the descriptive tag, and the lockfile records which commit it resolved to when it was locked. GitHub also stores the numeric IDs of the owner and the repository. When a run starts, Actions takes the stored commit and checks whether the repository behind the name is still the locked one. A moved tag is not even resolved again during a normal run.

One thing matters for the big picture: the lockfile does not judge whether an action is good or bad. It makes sure that what you locked is what runs. If you lock a compromised version, you reliably get the compromised version. Reviewing before locking therefore remains mandatory.

At start, Actions takes the locked commit and checks the repository ID; a moved tag does not matter.

How the GitHub Actions lockfile is structured

The file always lives at .github/workflows/actions.lock, it is YAML and it is generated by the CLI extension. You should not edit it by hand. An excerpt for our bookshop looks roughly like this (the hashes are shortened):

# .github/workflows/actions.lock
# This file is machine-generated by `gh actions-lock`.
# Do not edit by hand; run `gh actions-lock` to update.
version: 'v0.0.2'
workflows:
    '.github/workflows/ci.yml':
        - 'actions/checkout@v7.0.1'
        - 'actions/setup-node@v6.0.0'
dependencies:
    'actions/checkout@v7.0.1':
        ref: 'v7.0.1'
        commit: 'sha1-...'
        owner_id: 44036562
        repo_id: 197814629
    'actions/setup-node@v6.0.0':
        ref: 'v6.0.0'
        commit: 'sha1-...'
        owner_id: 44036562
        repo_id: 123456789

The workflows section lists which workflow file uses which dependencies. Under dependencies you find, for each reference, the tag (ref), the resolved commit (commit) and both IDs. The IDs of setup-node in this excerpt are placeholders, your file contains the real values. A workflow counts as “onboarded” as soon as it is listed in the lockfile. From then on, every one of its action dependencies must appear there, and Actions runs the stored commit.

What the lockfile covers

It covers the actions in your workflows and their transitive dependencies, including what a composite action calls internally. Reusable workflows are an exception: their dependencies are covered by the lockfile of the repository in which the reusable workflow is defined. If your team maintains shared workflows in a central repository, that is where you should start.

Set up the GitHub Actions lockfile step by step

Our starting point is a plain CI workflow for the bookshop. It checks out the code, installs Node.js and runs the tests. The action versions here are only examples, use the ones you already rely on today.

# .github/workflows/ci.yml
name: ci

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: actions/setup-node@v6
        with:
          node-version: 22
      - run: npm ci
      - run: npm test

Prerequisites

The GitHub CLI gh, signed in via gh auth login, and write access to the repository.
A repository on github.com or in GitHub Enterprise Cloud with data residency. According to its README, the extension does not support GitHub Enterprise Server.
According to the changelog, lockfiles are available on the Free, Team and Enterprise Cloud plans. At the time of writing, some docs pages still carry the preview notice, so details may still change.
Recommended: Dependabot version updates for GitHub Actions are already enabled (more on that shortly).

Step 1: Install the extension

gh extension install github/gh-actions-lock
gh actions-lock --help

Later, gh extension upgrade gh-actions-lock fetches new versions. If you work with an AI coding agent, gh skill install github/gh-actions-lock teaches it to regenerate the lockfile itself after workflow changes. That is a convenience, not a control.

Step 2: Generate the lockfile

In the root directory of the repository, a single command generates the lockfile for all workflows under .github/workflows/. If you want to start small, pass individual files.

# all workflows at once
gh actions-lock

# or just one workflow to begin with
gh actions-lock .github/workflows/ci.yml

If the extension reports that it skips a workflow because of local actions, a reference of the form uses: ./… could not be resolved. Local paths always start at the repository root, not at the folder of the workflow file. For special cases there are the options --migrate-local-actions and --ignore-local-actions.

Step 3: Actually read the diff

Now comes the part many people skip. The extension changes more than just the lockfile. For example, it rewrites partial versions like @v7 to the full tag, i.e. @v7.0.1, while the commit stays the same. According to the docs, local references uses: ./… become uses: $/…, because they always belong to the commit that is currently running and need no lockfile entry. Use git diff to look at every changed file and then commit everything together.

git diff -- .github/
git add .github/workflows/
git commit -m "ci: lock GitHub Actions dependencies"

Step 4: Check your allowlists

This is where the most common pitfall hides. If your repository, organization or enterprise restricts the allowed actions, GitHub matches that list against the locked commit SHAs after the switch. An entry like actions/checkout@v6 will then no longer match. Replace such entries with a pattern like actions/checkout@* or with the full SHA before you push the commit.

After that, the CI workflow runs as before, just with pinned code. Expected result: a green run, and a new file actions.lock sitting next to your workflows in the repository.

Keep the lockfile current

A lockfile that is generated only once goes stale quickly. As soon as someone adds or removes an action, gh actions-lock has to run again. Four building blocks make sure this does not depend on anyone’s memory.

Dependabot updates the lockfile too

When Dependabot bumps the version of an action in an already onboarded workflow, it regenerates the matching lockfile entry in the same pull request, without extra configuration. However, Dependabot does not onboard new workflows by itself, it only reports that onboarding is missing. I like to combine this with a cooldown so that fresh releases can mature for a few days before they reach us.

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
    cooldown:
      default-days: 7

Check pull requests automatically

The command gh actions-lock --verify writes nothing, but runs the same checks as a normal run and exits with an error if the lockfile no longer matches the workflows. That makes it suitable as a required check. The extension’s repository ships a template; my variant adds a step that writes lockfile changes neatly into the job summary (we build the tool for that in the next section).

# .github/workflows/verify-lockfile.yml
name: verify-lockfile

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  verify:
    runs-on: ubuntu-latest
    env:
      GH_TOKEN: ${{ github.token }}
    steps:
      - uses: actions/checkout@v7.0.1
        with:
          persist-credentials: false
          fetch-depth: 0
      - run: gh extension install github/gh-actions-lock --pin v0.2.0
      # Fails if actions.lock does not match the workflows
      - run: gh actions-lock --verify
      - uses: actions/setup-node@v6
        with:
          node-version: 22
      - name: Summarize lockfile changes
        if: github.event_name == 'pull_request'
        env:
          BASE_REF: ${{ github.base_ref }}
        run: |
          git show "origin/$BASE_REF:.github/workflows/actions.lock" > "$RUNNER_TEMP/base.lock" 2>/dev/null || true
          npm ci --prefix tools/actions-lock-review
          node tools/actions-lock-review/src/cli.ts "$RUNNER_TEMP/base.lock" .github/workflows/actions.lock >> "$GITHUB_STEP_SUMMARY"

Two details matter to me here. The workflow deliberately has no paths filter, because a required check that does not even start for some PRs blocks merging. And the name of the target branch reaches the script through an environment variable instead of directly via ${{ }}, so no expression slips into the shell unchecked. After adding this workflow, run gh actions-lock once, because it uses actions too and has to be in the lockfile.

Pre-commit hook and CODEOWNERS

Locally, a hook helps that checks before every commit whether each dependency has an entry. It works offline and needs no authentication, but it does not verify the pins against GitHub. That remains the job of the CI check.

# .git/hooks/pre-commit (make it executable with chmod +x)
#!/bin/sh
gh actions-lock --verify-local --no-fix

So that lockfile changes do not slip through unnoticed, the file belongs in CODEOWNERS. Combined with a branch rule that requires code owner review, someone responsible for the pipeline always looks at new commits.

# .github/CODEOWNERS
/.github/workflows/actions.lock @bookshop/platform-team

🎬 Pull request with a changed action – this animated diagram only runs on my site: watch it on sascha-ms.de

Make lockfile changes visible in reviews

Nobody enjoys reading a YAML diff full of 40-character hashes. The docs name two signals that matter: a changed commit is new code that will run, so treat it like a version bump. A changed owner_id or repo_id should almost never happen and means that a different repository is behind the name. A small TypeScript tool that I keep in the folder tools/actions-lock-review/ highlights exactly these two cases.

Create the project

The tool runs directly on Node.js 22.18 or newer, which executes TypeScript without a build step as long as only “erasable” syntax such as type annotations is used. The only runtime dependency we need is the YAML parser yaml.

mkdir -p tools/actions-lock-review && cd tools/actions-lock-review
npm init -y
npm pkg set type=module
npm install yaml
npm install -D typescript @types/node

{
  "compilerOptions": {
    "target": "ES2024",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "types": ["node"]
  },
  "include": ["src", "test"]
}

Read the lockfile

The first file reads the lockfile and checks that the fields we rely on are present. Empty text stands for the first pull request, when there is no lockfile in the target branch yet.

// tools/actions-lock-review/src/lockfile.ts
import { parse } from "yaml";

export interface LockedDependency {
  ref: string;
  commit: string;
  owner_id: number;
  repo_id: number;
}

export interface ActionsLock {
  version: string;
  workflows: Record<string, string[]>;
  dependencies: Record<string, LockedDependency>;
}

// Reads the content of an actions.lock and checks the fields we need.
// Empty text means "there is no lockfile yet" (e.g. in the first PR).
export function parseLockfile(text: string): ActionsLock {
  if (text.trim() === "") {
    return { version: "none", workflows: {}, dependencies: {} };
  }
  const data = parse(text) as Partial<ActionsLock> | null;
  if (!data || typeof data !== "object") {
    throw new Error("actions.lock is not a valid YAML object");
  }
  const dependencies = data.dependencies ?? {};
  for (const [key, dep] of Object.entries(dependencies)) {
    if (!dep || typeof dep.commit !== "string" || typeof dep.repo_id !== "number" || typeof dep.owner_id !== "number") {
      throw new Error(`Entry "${key}" is incomplete (expected commit, owner_id, repo_id)`);
    }
  }
  return {
    version: String(data.version ?? "unknown"),
    workflows: data.workflows ?? {},
    dependencies,
  };
}

Find and report differences

The second file compares the lockfile of the target branch with the one from the pull request and produces a Markdown table that GitHub renders nicely in the job summary.

// tools/actions-lock-review/src/diff.ts
import type { ActionsLock } from "./lockfile.ts";

export type ChangeKind = "added" | "removed" | "commit" | "identity";

export interface LockChange {
  key: string;
  kind: ChangeKind;
  before?: string;
  after?: string;
}

const short = (sha: string) => sha.replace(/^sha1-/, "").slice(0, 12);

// Compares the lockfile from the target branch (base) with the one from the PR (head).
export function diffLockfiles(base: ActionsLock, head: ActionsLock): LockChange[] {
  const changes: LockChange[] = [];
  const keys = new Set([...Object.keys(base.dependencies), ...Object.keys(head.dependencies)]);

  for (const key of [...keys].sort()) {
    const oldDep = base.dependencies[key];
    const newDep = head.dependencies[key];

    if (!oldDep && newDep) {
      changes.push({ key, kind: "added", after: short(newDep.commit) });
    } else if (oldDep && !newDep) {
      changes.push({ key, kind: "removed", before: short(oldDep.commit) });
    } else if (oldDep && newDep) {
      // Different repository ID behind the same name: this is the dangerous case.
      if (oldDep.owner_id !== newDep.owner_id || oldDep.repo_id !== newDep.repo_id) {
        changes.push({
          key,
          kind: "identity",
          before: `${oldDep.owner_id}/${oldDep.repo_id}`,
          after: `${newDep.owner_id}/${newDep.repo_id}`,
        });
      } else if (oldDep.commit !== newDep.commit) {
        changes.push({ key, kind: "commit", before: short(oldDep.commit), after: short(newDep.commit) });
      }
    }
  }
  return changes;
}

const labels: Record<ChangeKind, string> = {
  added: "new",
  removed: "removed",
  commit: "different commit",
  identity: "DIFFERENT REPOSITORY",
};

// Builds a Markdown report you can use as a PR comment or job summary.
export function toMarkdown(changes: LockChange[]): string {
  if (changes.length === 0) {
    return "No changes to pinned actions.";
  }
  const rows = changes.map(
    (c) => `| ${c.key} | ${labels[c.kind]} | ${c.before ?? "–"} | ${c.after ?? "–"} |`,
  );
  return ["| Action | Change | before | after |", "| --- | --- | --- | --- |", ...rows].join("\n");
}

The command line connects both. If it finds a change of the repository ID, it exits with code 1 and the check turns red. New or changed commits are only reported, because they are normal with every Dependabot update.

// tools/actions-lock-review/src/cli.ts
import { readFile } from "node:fs/promises";
import { parseLockfile } from "./lockfile.ts";
import { diffLockfiles, toMarkdown } from "./diff.ts";

const [basePath, headPath] = process.argv.slice(2);
if (!basePath || !headPath) {
  console.error("Usage: node src/cli.ts <base.lock> <head.lock>");
  process.exit(2);
}

// If the file is missing in the target branch, we treat it as empty.
const readOrEmpty = (path: string) => readFile(path, "utf8").catch(() => "");

const base = parseLockfile(await readOrEmpty(basePath));
const head = parseLockfile(await readFile(headPath, "utf8"));
const changes = diffLockfiles(base, head);

console.log(toMarkdown(changes));

const identity = changes.filter((c) => c.kind === "identity");
if (identity.length > 0) {
  console.error(`Warning: ${identity.length} action(s) point to a different repository. Please review.`);
  process.exit(1);
}

Test it

The tests use the built-in Node.js test runner. They cover the normal case, a new commit, a foreign repository ID, the missing lockfile and broken entries.

// tools/actions-lock-review/test/diff.test.ts
import { test } from "node:test";
import assert from "node:assert/strict";
import { parseLockfile } from "../src/lockfile.ts";
import { diffLockfiles, toMarkdown } from "../src/diff.ts";

const base = parseLockfile(`
version: 'v0.0.2'
workflows:
  '.github/workflows/ci.yml':
    - 'actions/checkout@v7.0.1'
    - 'bookshop/deploy-action@v2.3.0'
dependencies:
  'actions/checkout@v7.0.1':
    ref: 'v7.0.1'
    commit: 'sha1-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
    owner_id: 44036562
    repo_id: 197814629
  'bookshop/deploy-action@v2.3.0':
    ref: 'v2.3.0'
    commit: 'sha1-bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'
    owner_id: 1001
    repo_id: 2002
`);

test("no change yields an empty list", () => {
  assert.deepEqual(diffLockfiles(base, base), []);
  assert.match(toMarkdown([]), /No changes/);
});

test("new commit is detected as a commit change", () => {
  const head = structuredClone(base);
  head.dependencies["bookshop/deploy-action@v2.3.0"].commit = "sha1-cccccccccccccccccccccccccccccccccccccccc";
  const changes = diffLockfiles(base, head);
  assert.equal(changes.length, 1);
  assert.equal(changes[0].kind, "commit");
  assert.equal(changes[0].after, "cccccccccccc");
});

test("different repo_id behind the same name is an identity finding", () => {
  const head = structuredClone(base);
  head.dependencies["bookshop/deploy-action@v2.3.0"].repo_id = 9999;
  const changes = diffLockfiles(base, head);
  assert.equal(changes[0].kind, "identity");
  assert.match(toMarkdown(changes), /DIFFERENT REPOSITORY/);
});

test("missing lockfile in target branch: everything is new", () => {
  const changes = diffLockfiles(parseLockfile(""), base);
  assert.deepEqual(changes.map((c) => c.kind), ["added", "added"]);
});

test("incomplete entries are rejected", () => {
  assert.throws(() => parseLockfile("dependencies:\n  'x/y@v1':\n    ref: 'v1'\n"), /incomplete/);
});

npx tsc --noEmit
node --test test/*.test.ts
node src/cli.ts base.lock ../../.github/workflows/actions.lock

Roll out the “Require lockfile” policy

Up to this point, the lockfile is voluntary. Repository, organization or enterprise administrators can make it mandatory with the “Require lockfile” policy. It blocks runs of workflows that use actions but are not onboarded to the repository’s lockfile. You find the setting among the rules that govern workflow execution. I find the order GitHub recommends sensible and would adopt it exactly like this:

Pilot: Apply the policy only to repositories and workflows that already have a lockfile.
Observe: Start in “Evaluate” mode and analyze the results under “Policy insights”. According to the docs, this mode is only available in GitHub Enterprise.
Automate: Set up Dependabot, the verify check and the hook so nobody has to run the lock command manually.
Enforce: Only then switch to “Active” and include all onboarded repositories.

The verify check stays active even after enforcement. The policy stops runs without a valid lockfile, while the check warns the author of a pull request beforehand. Without it, you only find out after the merge that the pipeline is stuck.

When a tag moves legitimately

If a tag like v7 or a branch like main points to a new commit after a regular release, gh actions-lock --relock brings the pins up to date. If the originally locked commit can no longer be reached upstream, for example after a force push, that fails as well. Only --relock --accept-moved accepts the new commit. This option never belongs in automation, so look at the history of the foreign repository first.

# pick up regular releases
gh actions-lock --relock

# only after a manual review: replace a vanished commit
gh actions-lock --relock --accept-moved

Common mistakes and how to avoid them

Symptom	Cause	Fix
Workflow is skipped during generation	Local action `./…` given relative to the workflow folder	Write the path from the repository root and regenerate
Actions are rejected after the switch	Allowlist contains tags like `@v6`	Use a pattern with `@*` or the full SHA
Required check hangs on “Expected”	Verify workflow has a `paths` filter	Remove the filter or do not mark the check as required
`--relock` fails	Locked commit was removed upstream	Check the history, then deliberately use `--accept-moved`
Rate limit during verify	Anonymous requests to github.com (60 per hour)	Set `GH_TOKEN`, as in the workflow above

The whole setup costs very little: the verify job is a short run on a standard runner, and in private repositories it counts towards your normal Actions minutes. In terms of security, the basic rule from above applies: the lockfile protects against surprising changes, while reviewing new versions remains human work.

My take

I consider the GitHub Actions lockfile one of the most useful GitHub features this year, precisely because it is unspectacular. It is the same principle we have long used with npm with a lockfile and a cooldown, finally applied to the pipeline, which often has more permissions than the application itself. Readability and security are no longer played off against each other, and that removes a lot of friction in teams.

I would push back on the feeling that this settles the supply chain topic for workflows. If you lock an action without looking at it, you have merely frozen the problem. Keeping the permissions of the GITHUB_TOKEN small, handing out secrets sparingly and choosing third-party actions consciously remain just as important as before. My advice: start in the repository that holds your shared workflows, and give yourself half an hour for the first diff. It rarely takes more.

FAQ

Do I still need to pin actions by SHA in the workflow?

According to the GitHub docs, SHA pinning in the workflow is no longer necessary once a repository uses the lockfile. You can keep readable tags like @v7.0.1, and the commit lives in the lockfile.

Which GitHub plans include workflow lockfiles?

According to the changelog from October 28, 2026: Free, Team, Enterprise Cloud and Enterprise Cloud with data residency. The “Evaluate” mode of the mandatory policy is only available in GitHub Enterprise, and the CLI extension does not support GitHub Enterprise Server.

Does the lockfile also cover reusable workflows?

Only indirectly. The dependencies of a reusable workflow are locked by the lockfile of the repository in which that workflow lives. That is why you should switch central workflow repositories first.

May I edit actions.lock by hand?

No. If an entry looks wrong, fix the workflow files and regenerate the lockfile with gh actions-lock.

Your next step

Pick a single repository today, ideally the one with your shared workflows: install the extension, run gh actions-lock, read the diff calmly, check the allowlist, commit. The verify check and Dependabot follow in the second pull request. You can find more posts on secure pipelines in the English blog archive.

I am curious: do you already pin your actions by SHA today, or do you rely on tags? And what has kept you from changing that so far? Let me know in the comments.

Sources

GitHub Changelog: GitHub Actions workflow lockfiles are generally available (Oct 28, 2026)
GitHub Docs: Workflow dependency lockfiles
GitHub Docs: Locking action dependencies in a repository’s workflows
GitHub Docs: Enforcing lockfiles for action dependencies
github/gh-actions-lock (README, MIT license)
GitHub Docs: Dependabot options reference (cooldown)
Tested with Node.js 22.23, TypeScript 7.0.2 (tsc --noEmit), yaml 2.9.1 and the Node test runner (5 tests). The YAML files were parsed for valid syntax; the workflows themselves and gh actions-lock were not executed.

This post was created with AI assistance.

👉 Next step: Not sure which AWS service fits your use case? My AWS service finder asks a few questions and points you to the right one.

Originally published on sascha-ms.de. More articles on serverless, AI in everyday development and leading tech teams: sascha-ms.de/en

Copilot Assisted Permissions: a safe setup

Sascha Mirow-Stanitzok — Sun, 01 Nov 2026 14:56:00 +0000

Copilot Assisted Permissions became generally available on October 26, 2026, in Copilot CLI, the GitHub Copilot app and VS Code. The idea: a language model looks at every approval request from the agent and waves through the clearly harmless ones on its own. Only the rest still reaches you.

I care about this topic because I know the alternative. If you let a coding agent work for an hour, at some point you approve every prompt without reading it. Or you start with --yolo right away. Both feel productive, and neither is. In this article we look at how the new mode decides, how to set it up, and which rules keep “fewer clicks” from turning into “less control”.

In short

Assisted permissions lets a review model approve clearly safe commands, file access and URLs, and only asks you when in doubt. That saves many clicks in daily work, but it replaces neither deny rules nor a sandbox. The biggest pitfall is combining it with --allow-all-tools in CI: if the mode cannot be enabled, the agent runs without any review.

What you will learn in this article

How the three approval modes in GitHub Copilot differ
In which order rules, earlier approvals and the review model decide
How to turn the mode on in the CLI, the app and VS Code
How to set firm guardrails with allow, ask and deny, and check them with TypeScript
What to watch out for when you use it in CI pipelines

What are Copilot Assisted Permissions?

A coding agent (an AI assistant that runs commands, edits files and fetches web pages on its own) needs permission for almost everything. GitHub Copilot now offers three modes for this. In manual mode, Copilot asks before every command that is not read-only, before every file edit and before every URL fetch. An approval can cover a single action or the whole session.

The opposite end is called “unconditional approval” in the docs and is better known as allow-all or YOLO mode. Copilot may then use tools, paths and URLs without prompts and without a model review. Deny rules and your company’s policies still apply; everything else goes through.

Assisted permissions sits right in between. A review model rates every eligible request in the context of your task. If it is confident that the action is harmless and fits the assignment, the action runs without a prompt. If not, Copilot asks you, just like in manual mode. The phrase “in the context of the task” matters: npm test is unremarkable while fixing a test, a curl to an unknown domain while renaming a variable is less so.

The three approval modes compared: assisted only asks when the review model is unsure.

Mode	Who reviews?	When does it make sense?
Manual	You, for every action	Unfamiliar repositories, work close to production, first steps with a new agent
Assisted	Rules, then the review model, you when in doubt	Daily work in your own repository with clear guardrails
Allow-all	Only deny rules and company policies	Throwaway environments such as containers or dev VMs without credentials

How does the review model decide?

The order is the key to understanding it. According to the GitHub docs, Copilot first checks existing rules and earlier approvals from the session. Anything already allowed runs without a prompt and without a model review. Anything that hits a deny rule is stopped. Only the remaining requests go to the review model, and only three kinds: running commands, accessing paths and fetching URLs.

After that there are three outcomes. If the model is confident, the action runs. If it is unsure, Copilot asks you. If the review cannot take place at all, for example because the service is unavailable, the session’s normal approval handling applies. In autopilot mode and in non-interactive runs, there is no human to ask. That is why uncertain requests are denied there, and Copilot receives the explanation so it can try another approach.

🎬 How an approval works with Copilot Assisted Permissions – this animated diagram only runs on my site: watch it on sascha-ms.de

What the review does not cover

You should know three limitations before you rely on the mode. First, the model leaves out further tool calls that an enterprise rule explicitly requires you to approve, such as certain MCP tools. Second, requests to bypass a local sandbox stay under normal handling. Third, GitHub states very clearly that the model can make mistakes and may approve dangerous actions too. Assisted permissions is explicitly not a replacement for a sandbox or access restrictions.

In addition, Copilot picks the review model itself. It can differ from the model you are currently working with. With a model provider of your own, your session’s active model handles the review.

Prerequisites

Copilot access where your company has not disabled the mode by policy
Copilot CLI (for example installed with npm install -g @github/copilot), the GitHub Copilot app, or VS Code with Copilot
For the check script below: Node.js 22 and TypeScript
A repository where you can experiment safely. A small, made-up library app is all you need

Set up Copilot Assisted Permissions step by step

Setup is quick. The real effort lies in the rules you build around it. So we go from switching it on, to the default, to a checked policy.

Step 1: Turn on the mode for one session

In an interactive CLI session, one slash command is enough. It applies only to the current session, and you can switch back at any time, even in the middle of a task.

/permissions assisted
/permissions show
/permissions manual

/permissions show displays the active mode. Without an argument, /permissions opens a picker. Expected result: after switching, Copilot asks far less often for routine commands such as git status or npm test.

Step 2: Make assisted the default

To start new interactive sessions in assisted mode right away, set the key defaultPermissionMode in ~/.copilot/settings.json. Alternatively, use /settings during a session.

{
  "defaultPermissionMode": "assisted"
}

Two details matter. If an administrator has set permissions.defaultMode, that value wins. And if the chosen mode is blocked by policy, the CLI starts in manual mode. Resumed sessions keep their saved mode.

Step 3: Copilot app and VS Code

In the GitHub Copilot app, open the mode menu in the prompt box, choose “Tool permissions” and then “Assisted”. This applies to the current session and also becomes the default for new local sessions. To change only the default, go to Settings, Sessions. Cloud sessions do not have this setting. In VS Code, pick “Assisted permissions” in the permissions picker.

Step 4: Guardrails with allow, ask and deny

Now comes the part that turns a convenience feature into a setting you can justify. With managed settings (a managed-settings.json that the company distributes via file, MDM or server) you define what is never allowed, what needs fresh consent and what is always allowed. Precedence is clear: deny beats ask, ask beats allow.

{
  "permissions": {
    "disableBypassPermissionsMode": "disable",
    "defaultMode": "assisted",
    "deny": [
      "Read(~/.ssh/**)",
      "Read(~/.aws/**)",
      "Edit(/.github/workflows/**)",
      "Shell(rm -rf *)"
    ],
    "ask": [
      "Shell(git push *)",
      "Shell(npm publish *)",
      "Domain(api.github.com)"
    ],
    "allow": [
      "Shell(npm test *)",
      "Shell(npx tsc *)",
      "Read(/src/**)",
      "Domain(registry.npmjs.org)"
    ]
  }
}

A few notes on the selectors: Shell(...) matches shell commands, where git push * works as a prefix and anything without an asterisk is compared exactly. Read(...) and Edit(...) use globs and know the roots // for the file system, / for the workspace, ~/ for the home directory and ./ for the current directory. Domain(...) controls network targets.

With disableBypassPermissionsMode you turn off YOLO mode without losing assisted. One interaction matters here: in the CLI, the review model can satisfy managed ask rules for shell, files and URLs. So an ask rule does not necessarily mean you will be asked. If you really want to decide on every git push yourself, move the rule to deny and push by hand.

Step 5: Check the policy automatically

Rule files grow, and at some point someone adds "defaultMode": "allow-all" for a quick test and forgets it. That is why an automatic check pays off. The small TypeScript module below reports typical gaps: unknown selectors, an allowed YOLO mode, missing blocks for ~/.ssh and ~/.aws, an unprotected git push, missing domain rules, and rules that never apply.

// src/policy.ts
// Checks a Copilot permission policy (managed-settings.json) for common gaps.

export type Severity = "error" | "warning" | "info";

export interface Finding {
  severity: Severity;
  rule: string;
  message: string;
}

export interface PermissionSettings {
  allow?: string[];
  ask?: string[];
  deny?: string[];
  defaultMode?: "manual" | "assisted" | "allow-all";
  disableBypassPermissionsMode?: "disable";
  disableAssistedPermissionsMode?: boolean;
}

export interface CopilotSettings {
  permissions?: PermissionSettings;
}

const SELECTOR = /^(Shell|Bash|PowerShell|Read|Edit|Write|Domain)\((.+)\)$/;

// Paths a coding agent should never read.
const SECRET_PATHS = ["~/.ssh/", "~/.aws/"];

export function checkPolicy(settings: CopilotSettings): Finding[] {
  const findings: Finding[] = [];
  const p = settings.permissions ?? {};
  const allow = p.allow ?? [];
  const ask = p.ask ?? [];
  const deny = p.deny ?? [];

  // 1. Every rule must use a known selector.
  for (const [list, rules] of Object.entries({ allow, ask, deny })) {
    for (const rule of rules) {
      if (!SELECTOR.test(rule)) {
        findings.push({ severity: "error", rule, message: `Unknown format in "${list}".` });
      }
    }
  }

  // 2. The free-pass mode should be turned off.
  if (p.disableBypassPermissionsMode !== "disable") {
    findings.push({
      severity: "warning",
      rule: "disableBypassPermissionsMode",
      message: 'Allow-all/YOLO is allowed. Recommendation: "disable".',
    });
  }

  if (p.defaultMode === "allow-all") {
    findings.push({
      severity: "error",
      rule: "defaultMode",
      message: "New sessions start without any review. Better: manual or assisted.",
    });
  }

  // 3. Secrets in the home directory must be blocked.
  for (const path of SECRET_PATHS) {
    const covered = deny.some((r) => r.startsWith(`Read(${path}`));
    if (!covered) {
      findings.push({
        severity: "error",
        rule: `Read(${path}**)`,
        message: `Reading ${path} is not denied.`,
      });
    }
  }

  // 4. git push should always need a fresh approval.
  const pushGuarded = [...ask, ...deny].some((r) => /^(Shell|Bash)\(git push/.test(r));
  if (!pushGuarded) {
    findings.push({
      severity: "warning",
      rule: "Shell(git push *)",
      message: "git push is in neither ask nor deny.",
    });
  }

  // 5. Without domain rules the agent may request any URL it considers safe.
  const hasDomainRule = [...allow, ...ask, ...deny].some((r) => r.startsWith("Domain("));
  if (!hasDomainRule) {
    findings.push({
      severity: "info",
      rule: "Domain(...)",
      message: "No domain rules. A small allowlist makes network access traceable.",
    });
  }

  // 6. Rules that are both allowed and denied: deny wins, the allow rule is dead code.
  for (const rule of allow) {
    if (deny.includes(rule)) {
      findings.push({ severity: "info", rule, message: "Listed in allow and deny – deny wins." });
    }
  }

  // 7. Shell rules without " *" only match exactly.
  for (const rule of allow) {
    const m = SELECTOR.exec(rule);
    if (m && (m[1] === "Shell" || m[1] === "Bash") && !m[2].endsWith(" *") && m[2].split(" ").length < 3) {
      findings.push({
        severity: "info",
        rule,
        message: 'Matches only this exact command. Append " *" for variants.',
      });
    }
  }

  return findings;
}

Next, a lean command-line entry point that exits with code 1 on errors. That way you can plug it straight into a pipeline.

// src/cli.ts
// Usage: node dist/src/cli.js managed-settings.json
import { readFileSync } from "node:fs";
import { checkPolicy, type CopilotSettings } from "./policy.js";

const file = process.argv[2] ?? "managed-settings.json";
const settings = JSON.parse(readFileSync(file, "utf8")) as CopilotSettings;
const findings = checkPolicy(settings);

for (const f of findings) {
  console.log(`${f.severity.toUpperCase().padEnd(8)} ${f.rule}  ${f.message}`);
}

const errors = findings.filter((f) => f.severity === "error").length;
console.log(`\n${findings.length} findings, ${errors} of them errors.`);
process.exitCode = errors > 0 ? 1 : 0;

The tests run with the built-in Node.js test runner, without any extra library.

// test/policy.test.ts
import { test } from "node:test";
import assert from "node:assert/strict";
import { checkPolicy } from "../src/policy.js";

const solid = {
  permissions: {
    disableBypassPermissionsMode: "disable" as const,
    defaultMode: "assisted" as const,
    deny: ["Read(~/.ssh/**)", "Read(~/.aws/**)", "Shell(rm -rf *)"],
    ask: ["Shell(git push *)", "Domain(api.github.com)"],
    allow: ["Shell(npm test *)", "Read(/src/**)", "Domain(registry.npmjs.org)"],
  },
};

test("a solid policy has no errors or warnings", () => {
  const f = checkPolicy(solid);
  assert.equal(f.filter((x) => x.severity !== "info").length, 0);
});

test("empty settings report missing blocks", () => {
  const f = checkPolicy({});
  const rules = f.map((x) => x.rule);
  assert.ok(rules.includes("disableBypassPermissionsMode"));
  assert.ok(rules.includes("Read(~/.ssh/**)"));
  assert.ok(rules.includes("Shell(git push *)"));
});

test("allow-all as default is an error", () => {
  const f = checkPolicy({ permissions: { ...solid.permissions, defaultMode: "allow-all" } });
  assert.ok(f.some((x) => x.rule === "defaultMode" && x.severity === "error"));
});

test("unknown selectors are detected", () => {
  const f = checkPolicy({ permissions: { ...solid.permissions, allow: ["Exec(make)"] } });
  assert.ok(f.some((x) => x.rule === "Exec(make)" && x.severity === "error"));
});

test("exact shell rules get a hint", () => {
  const f = checkPolicy({ permissions: { ...solid.permissions, allow: ["Shell(npm test)"] } });
  assert.match(f.find((x) => x.rule === "Shell(npm test)")?.message ?? "", /this exact command/);
});

test("conflicts between allow and deny are reported", () => {
  const f = checkPolicy({
    permissions: { ...solid.permissions, allow: ["Read(~/.aws/**)"] },
  });
  assert.ok(f.some((x) => x.rule === "Read(~/.aws/**)" && /deny wins/.test(x.message)));
});

To run it, you need a package.json with "type": "module" and a tsconfig.json with "module": "NodeNext". Then these commands are enough:

npm install --save-dev typescript @types/node
npx tsc
node --test dist/test/*.test.js
node dist/src/cli.js managed-settings.json

For the sample policy above, the script reports no findings. An empty file, on the other hand, yields five findings, two of them errors, and exit code 1:

WARNING  disableBypassPermissionsMode  Allow-all/YOLO is allowed. Recommendation: "disable".
ERROR    Read(~/.ssh/**)  Reading ~/.ssh/ is not denied.
ERROR    Read(~/.aws/**)  Reading ~/.aws/ is not denied.
WARNING  Shell(git push *)  git push is in neither ask nor deny.
INFO     Domain(...)  No domain rules. A small allowlist makes network access traceable.

5 findings, 2 of them errors.

Step 6: Assisted permissions in CI runs

Without a terminal, for example in a pipeline, you enable the mode with --assisted-approval together with -p, or with the environment variable COPILOT_ASSISTED_APPROVAL=true. Uncertain requests are denied here instead of prompted. On top of that, it pays to block pushing explicitly:

copilot -p "Fix the failing tests in src/" \
  --assisted-approval \
  --deny-tool 'shell(git push)'

Watch out for the different syntax: on the command line the patterns are written as shell(git push) or shell(git:*), in managed settings as Shell(git push *). It is easy to mix them up.

Common mistakes and how to avoid them

Combining assisted with allow-all flags. --assisted-approval does take precedence over --allow-all-tools, but it changes nothing about --allow-all-paths and --allow-all-urls. Even trickier: if the mode cannot be enabled, for instance because of a company policy, the CLI only writes a warning to stderr. An additional --allow-all-tools then stays active, and the agent works without review. So simply leave the allow-all flags out in CI and read the output of your runs.

Treating ask rules as a hard boundary. As described above, in the CLI the review model can satisfy ask rules for shell, files and URLs. Anything that must never happen without you belongs in deny.

Mistaking exact shell rules for prefixes. Shell(npm test) only matches exactly that command, not npm test -- --watch. For variants, you need Shell(npm test *).

Using the flag interactively. If you start an interactive session with --assisted-approval, the CLI exits with an error. In interactive mode, use /permissions assisted or defaultPermissionMode.

Forgetting old approvals. Location-scoped approvals are stored in ~/.copilot/permissions-config.json, approved URLs in allowedUrls in the settings. Both persist across sessions. /reset-allowed-tools cleans up for the current directory, after which the mode is back to manual.

Security, data and cost

The most important sentence on security is in the docs themselves: the mode reduces prompts, but it does not take away your responsibility for the agent’s actions. A language model judging the suggestions of another language model is a second opinion, not a security boundary. You draw the hard line with deny rules and a sandbox. The local sandbox in Copilot CLI works deny-by-default: every path is either read/write, read-only or denied. /sandbox status shows whether it is on, and /sandbox policy shows the effective policy.

On data, the assisted permissions page says nothing about how review requests are stored or logged. If that matters where you work, clarify it with the right people before rolling it out widely. The announcement does not give details on the cost of review calls either. A look at your organization’s usage reports after the first few weeks brings clarity here.

Agree on team rules for AI agents

Technology alone is not enough here. Whether a team uses Copilot Assisted Permissions is also a question of trust and responsibility. It works best to agree on it together in a short meeting rather than announce it by email. These questions help:

Which actions must never happen without a human, no matter how confident the model is?
In which repositories is assisted enough, and where do we stay with manual?
Who maintains the shared rule file, and how do we review changes to it?
How do we notice that an agent did something unexpected, and how do we talk about it without looking for someone to blame?
When do we look at our experience together, for example in the next retro?

The fourth point matters a lot to me. When an agent messes up, it was rarely the fault of the person who started it. Usually a rule was missing. A team that talks about it this way improves the rules. A team that looks for culprits quietly turns the mode off, or quietly switches to YOLO.

My take

I think Copilot Assisted Permissions is a good idea because it tackles a real problem: approval fatigue. A hundred prompts a day do not lead to a hundred conscious decisions, they lead to reflexive clicking. Fewer but relevant prompts are safer in the end.

I would push back on anyone selling the mode as a security feature. It is a convenience feature with a built-in gut feeling. Against targeted prompt injection, meaning hidden instructions in an issue description or a fetched web page, a model that judges “in the context of the task” only helps to a degree. After all, the manipulated context is exactly the problem. So my order is: deny rules and sandbox first, then assisted, and allow-all only in environments you throw away after the run. If you already work with Claude Code, you know the principle from my article on Claude Code hooks as guardrails. The tools differ, the pattern is the same.

FAQ

Are Copilot Assisted Permissions safe?

They are safer than allow-all, but not a security mechanism in the strict sense. The review model can be wrong. So combine the mode with deny rules and the local sandbox.

How do I turn on assisted permissions in Copilot CLI?

For one session with /permissions assisted, permanently via "defaultPermissionMode": "assisted" in ~/.copilot/settings.json, and for non-interactive runs with --assisted-approval together with -p.

Can my company block the mode?

Yes. With permissions.disableAssistedPermissionsMode: true in managed settings it is blocked. Conversely, disableBypassPermissionsMode: "disable" turns off only YOLO mode.

Which model reviews the requests?

Copilot chooses the review model itself, and it can differ from the model in your conversation. If it is unavailable, or if you bring your own model provider, your session’s active model handles the review.

Your next step

Pick one of your own repositories, switch on /permissions assisted for an hour and note which actions Copilot still asks about. Your first allow and deny lists almost write themselves from that. Then run them through the check script. I’d like to know: which action would you never let an agent take without asking, no matter how confident it is? Let me know in the comments.

Sources

This post was created with AI assistance.

👉 Next step: New here? My start page collects the best articles, tools and learning paths in one place.

Originally published on sascha-ms.de. More articles on serverless, AI in everyday development and leading tech teams: sascha-ms.de/en

Webhook retries: reliable delivery with SQS and Lambda

Sascha Mirow-Stanitzok — Sun, 01 Nov 2026 13:59:04 +0000

Webhook retries are one of those topics almost nobody thinks about until the first partner calls and asks why no orders have reached them since yesterday. A webhook is quick to build: an HTTP POST to someone else’s URL, done. What happens when the other side is in the middle of a deployment, returns 503 for a minute or simply does not answer is not covered in many implementations. Then the event is gone.

The topic matters to me because webhooks are where a cleanly built event-driven system leaves its own garden. Inside AWS, SQS, EventBridge and Lambda take care of retries. With a foreign URL, you are on your own. So in this eighth part of the series, I show you how I would build webhook retries today: with a queue, exponential backoff, signed messages and a dead-letter queue for the case where nothing works anymore.

In short

The best way to send webhooks is as jobs through an SQS queue: a Lambda function delivers them and retries failures with a growing delay via ChangeMessageVisibility. Every message carries a fixed ID and an HMAC signature so the receiver can spot duplicates and reject forgeries. The biggest pitfall is assuming that “send once” is enough: without retries, a DLQ and an alarm, you lose events without noticing.

What you will learn in this article

How to deliver webhooks reliably through SQS with exponential backoff
Which HTTP status codes trigger a new attempt and which do not
How to sign and verify webhooks with HMAC in the Standard Webhooks format
How to deploy and test everything with the Serverless Framework and TypeScript

Why webhooks get lost so easily

The obvious approach looks like this: an order gets paid, the code stores it and right after that calls every partner’s webhook URL. That always works in testing. In production, you run into receivers that are restarting, load balancers with their own timeouts and networks that simply drop a packet. A single attempt is therefore a bet that everything is fine on the receiver’s side at the exact moment of the event.

There is a second problem. If the call sits in the request path, your own customer waits for the response of a foreign system. If the partner answers slowly, your API becomes slow. Without any answer at all, your Lambda function runs into its timeout. That is exactly the coupling you wanted to avoid with an event-driven architecture.

A webhook is a message to a system you do not control. For messages like that, you need the same tools as for any other unreliable target: decoupling through a queue, retries with a delay and a place for messages that failed for good. I explained the basics of delays with a random component in detail in the article Exponential backoff with jitter. Here, the focus is on what that looks like for webhooks.

Webhook retries with SQS: the architecture at a glance

The example is once again a fictional ticket shop called “Kartenkiste”. When an order is paid or refunded, partners should learn about it, for example a point-of-sale system at the box office or an admission app. Each partner registers a URL and gets its own signing secret.

From event to partner: dispatch, delivery queue, deliverer and DLQ with alarm

The flow has two stages. The shop publishes an event such as OrderPaid on the EventBridge bus. A small dispatch function reads from a DynamoDB table who subscribed to this event and puts one delivery job per subscriber into an SQS queue. A second function, the deliverer, picks up the jobs from the queue, signs them and sends them to the partner via HTTP. If delivery fails, the job stays in the queue and comes back after a growing delay. After eight attempts, SQS moves it to a dead-letter queue (DLQ), a storage area for messages that cannot be processed. A CloudWatch alarm fires as soon as something lands there.

Why a queue instead of retries in code

You could simply write a loop with await sleep() in the deliverer. That has three drawbacks. First, Lambda bills you for every second the function waits. Second, the function stops after 15 minutes at the latest, because Lambda does not run longer. Third, the job is lost when the function crashes or gets redeployed. For webhook retries, a queue solves all three: the message sits safely in SQS while nobody pays for compute time, and the delay can be hours.

In addition, the queue keeps partners apart from each other. If one receiver hangs, only its own jobs are affected. The same principle is behind the fan-out with SNS and SQS: every consumer gets its own lane.

Aren’t EventBridge API destinations enough?

A fair question, because EventBridge can call HTTP endpoints directly through API destinations. According to the documentation, EventBridge retries errors such as 429 and 5xx for up to 24 hours by default, reads the Retry-After header and supports a DLQ. For internal targets or a handful of fixed partners, that is a good choice because you do not need any code of your own.

With real webhooks, however, I run into limits. A request may take five seconds at most, authentication is limited to basic auth, OAuth or an API key, and every new subscriber needs its own rule with a connection. An HMAC signature over the body per subscriber is not part of it. As soon as partners register themselves and are supposed to verify their messages, your own delivery through SQS is more flexible.

The rules: when is a webhook delivered?

Before you implement webhook retries, it pays to agree on clear rules with the receivers. For that, I follow the open specification Standard Webhooks, which several vendors developed together. It defines three headers: webhook-id is a unique ID that stays the same for every attempt. webhook-timestamp contains the time of sending in seconds. webhook-signature carries an HMAC-SHA256 signature over ID, timestamp and body, prefixed with v1,.

For the receiver’s responses, I use these rules:

Receiver response	What the deliverer does
2xx (200 to 299)	Delivered, the message is deleted
410 Gone	The receiver no longer wants webhooks: disable the subscription, do not retry
429 or 503 with `Retry-After`	Try again, at the earliest after the given time
3xx (redirect)	Do not follow, treat as a failure and retry
All other 4xx and 5xx	Try again with a growing delay
Timeout or network error	Try again with a growing delay

The other 4xx codes are debatable. A 400 or 404 often points to a permanent problem, and retries only postpone the error. On the other hand, many systems briefly return a 404 or 401 during a deployment. Here I stick to the specification and retry everything except 410, because lost events are usually more expensive for partners than a few unnecessary attempts.

Step by step: building webhook retries with Lambda

Now for the code. The project consists of a few small modules that you can test one by one.

Prerequisites: Node.js 22, an AWS account with configured credentials, the Serverless Framework v4 (npm i -g serverless) and basic TypeScript knowledge. I tested the code with TypeScript 7.0.2, Node.js 22.23 and the AWS SDK for JavaScript 3.1159.0.

Step 1: Create the project

Create an empty directory and install the dependencies. The tests run with the built-in Node.js test runner, so you need neither Jest nor Vitest.

mkdir kartenkiste-webhooks && cd kartenkiste-webhooks
npm init -y
npm i @aws-sdk/client-sqs @aws-sdk/client-ssm @aws-sdk/client-dynamodb
npm i -D typescript @types/node@22 @types/aws-lambda
mkdir src test

In package.json, set "type": "module" and two scripts. The --experimental-strip-types option lets Node.js run the TypeScript files directly without compiling them first.

{
  "name": "webhook-retries",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "typecheck": "tsc --noEmit",
    "test": "node --test --experimental-strip-types test/*.test.ts"
  },
  "dependencies": {
    "@aws-sdk/client-dynamodb": "^3.1159.0",
    "@aws-sdk/client-sqs": "^3.1159.0",
    "@aws-sdk/client-ssm": "^3.1159.0"
  },
  "devDependencies": {
    "@types/aws-lambda": "^8.10.164",
    "@types/node": "^22.19.0",
    "typescript": "^7.0.2"
  }
}

{
  "compilerOptions": {
    "target": "ES2023",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "erasableSyntaxOnly": true,
    "skipLibCheck": true,
    "types": ["node"]
  },
  "include": ["src", "test"]
}

Step 2: Sign webhooks

The signature is the first thing I build, because sender and receiver must understand it the same way. HMAC stands for “hash-based message authentication code”: a shared secret and the content produce a check value that only someone with the same secret can create. The string that gets signed is <id>.<timestamp>.<body>. Because the timestamp is included, an attacker cannot simply resend an intercepted message later.

// src/signature.ts
import { createHmac, timingSafeEqual } from 'node:crypto';

// Secrets in the Standard Webhooks format: "whsec_" + base64
function secretKey(secret: string): Buffer {
  const raw = secret.startsWith('whsec_') ? secret.slice(6) : secret;
  return Buffer.from(raw, 'base64');
}

// Signs "<id>.<timestamp>.<body>" with HMAC-SHA256 and returns "v1,<base64>"
export function signWebhook(secret: string, id: string, timestamp: number, body: string): string {
  const mac = createHmac('sha256', secretKey(secret))
    .update(`${id}.${timestamp}.${body}`)
    .digest('base64');
  return `v1,${mac}`;
}

export interface VerifyInput {
  secret: string;
  id: string | undefined;
  timestamp: string | undefined;
  signatureHeader: string | undefined;
  body: string; // the raw body, never re-serialized JSON
  nowSeconds?: number;
  toleranceSeconds?: number;
}

// Receiver side: check the timestamp, then compare every signature in the header
export function verifyWebhook(input: VerifyInput): boolean {
  const { secret, id, timestamp, signatureHeader, body } = input;
  if (!id || !timestamp || !signatureHeader) return false;

  const ts = Number(timestamp);
  if (!Number.isInteger(ts)) return false;
  const now = input.nowSeconds ?? Math.floor(Date.now() / 1000);
  if (Math.abs(now - ts) > (input.toleranceSeconds ?? 300)) return false;

  const expected = Buffer.from(signWebhook(secret, id, ts, body));
  // Multiple signatures are separated by spaces (key rotation)
  return signatureHeader.split(' ').some((candidate) => {
    const given = Buffer.from(candidate);
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
}

Two details matter. timingSafeEqual compares in constant time so that nobody can guess the signature character by character from response times. And the header may contain several signatures separated by spaces. That way you can rotate a secret without receivers rejecting messages during the transition.

Step 3: Calculate delays

The heart of webhook retries is the delay. It grows by a factor of three with every attempt: one minute, three, nine, 27 and so on, capped at six hours. To keep all failed messages from coming back at the same time, half of the delay is random. With eight attempts, this results in a window of roughly six to twelve hours. That covers a partner outage overnight without keeping messages around for days.

// src/backoff.ts
const BASE_SECONDS = 60;
const FACTOR = 3;
const MAX_DELAY_SECONDS = 6 * 60 * 60; // 6 hours, SQS allows at most 12
const MAX_RETRY_AFTER_SECONDS = 12 * 60 * 60;

// Exponentially growing delay (1, 3, 9, 27 … minutes) with "equal jitter":
// half of it is fixed, the other half is random
export function retryDelaySeconds(attempt: number, random: () => number = Math.random): number {
  const exp = Math.min(MAX_DELAY_SECONDS, BASE_SECONDS * FACTOR ** Math.max(0, attempt - 1));
  const half = exp / 2;
  return Math.max(1, Math.round(half + random() * half));
}

// Retry-After may contain seconds or an HTTP date
export function parseRetryAfter(value: string | null, nowMs: number = Date.now()): number | undefined {
  if (!value) return undefined;
  const trimmed = value.trim();
  let seconds: number;
  if (/^\d+$/.test(trimmed)) {
    seconds = Number(trimmed);
  } else {
    const date = Date.parse(trimmed);
    if (Number.isNaN(date)) return undefined;
    seconds = Math.ceil((date - nowMs) / 1000);
  }
  return Math.min(MAX_RETRY_AFTER_SECONDS, Math.max(1, seconds));
}

If the receiver sends a Retry-After header, it takes precedence. It may contain a number of seconds or an HTTP date, so the function handles both forms.

Step 4: Send a webhook

The sendWebhook function builds the body exactly once, signs this string and sends it. After that, it sorts the result into one of three categories: delivered, unsubscribed or try again.

// src/deliver.ts
import { parseRetryAfter } from './backoff.ts';
import { signWebhook } from './signature.ts';

export interface DeliveryJob {
  webhookId: string;   // stays the same for every attempt
  subscriberId: string;
  eventType: string;
  url: string;
  payload: unknown;
  occurredAt: string;
}

export type DeliveryResult =
  | { kind: 'delivered'; status: number }
  | { kind: 'gone' }
  | { kind: 'retry'; reason: string; retryAfterSeconds?: number };

export type FetchFn = typeof fetch;

export async function sendWebhook(
  job: DeliveryJob,
  secret: string,
  fetchFn: FetchFn = fetch,
  nowSeconds: number = Math.floor(Date.now() / 1000),
  timeoutMs = 10_000,
): Promise<DeliveryResult> {
  // Serialize the body exactly once: this string is signed and sent
  const body = JSON.stringify({ type: job.eventType, timestamp: job.occurredAt, data: job.payload });

  let response: Response;
  try {
    response = await fetchFn(job.url, {
      method: 'POST',
      redirect: 'manual', // do not follow redirects
      signal: AbortSignal.timeout(timeoutMs),
      headers: {
        'content-type': 'application/json',
        'user-agent': 'Kartenkiste-Webhooks/1.0',
        'webhook-id': job.webhookId,
        'webhook-timestamp': String(nowSeconds),
        'webhook-signature': signWebhook(secret, job.webhookId, nowSeconds, body),
      },
      body,
    });
  } catch (error) {
    // Timeout, DNS error, refused connection: try again later
    const name = error instanceof Error ? error.name : 'Error';
    return { kind: 'retry', reason: `network:${name}` };
  }

  // Discard the body so the connection is released
  await response.body?.cancel().catch(() => undefined);

  if (response.status >= 200 && response.status < 300) {
    return { kind: 'delivered', status: response.status };
  }
  if (response.status === 410) {
    return { kind: 'gone' };
  }
  return {
    kind: 'retry',
    reason: `http:${response.status}`,
    retryAfterSeconds: parseRetryAfter(response.headers.get('retry-after')),
  };
}

The ten-second limit comes from AbortSignal.timeout. The specification even recommends 15 to 30 seconds. I deliberately stay below that, because a Lambda function processes up to ten messages per invocation and a slow partner would otherwise hold up the whole batch. With redirect: 'manual', the deliverer does not follow redirects. A partner who has moved should update their URL instead of your messages silently ending up somewhere else.

Step 5: The deliverer with batch failures

Now comes the core of webhook retries. The function receives a batch from SQS and reports back through batchItemFailures which messages failed. Only those stay in the queue, Lambda deletes all others. To make this work, you have to enable the ReportBatchItemFailures option on the event source mapping.

The actual trick is ChangeMessageVisibility. Normally, a failed message becomes visible again after the queue’s visibility timeout expires, so always after the same time. If you set a new visibility timeout for exactly this message before reporting back, you decide yourself when it returns. SQS supplies the number of previous attempts in the ApproximateReceiveCount attribute.

🎬 Webhook retries with growing wait times – this animated diagram only runs on my site: watch it on sascha-ms.de

// src/handler.ts
import type { SQSBatchResponse, SQSEvent, SQSRecord } from 'aws-lambda';
import { ChangeMessageVisibilityCommand, SQSClient } from '@aws-sdk/client-sqs';
import { GetParameterCommand, SSMClient } from '@aws-sdk/client-ssm';
import { DynamoDBClient, UpdateItemCommand } from '@aws-sdk/client-dynamodb';
import { retryDelaySeconds } from './backoff.ts';
import { sendWebhook, type DeliveryJob, type DeliveryResult } from './deliver.ts';

export interface DeliveryDeps {
  maxAttempts: number;
  getSecret: (subscriberId: string) => Promise<string>;
  send: (job: DeliveryJob, secret: string) => Promise<DeliveryResult>;
  delayMessage: (receiptHandle: string, seconds: number) => Promise<void>;
  disableSubscription: (job: DeliveryJob) => Promise<void>;
  random?: () => number;
  log?: (entry: Record<string, unknown>) => void;
}

export function createDeliveryHandler(deps: DeliveryDeps) {
  const log = deps.log ?? ((entry) => console.log(JSON.stringify(entry)));

  async function processRecord(record: SQSRecord): Promise<boolean> {
    const job = JSON.parse(record.body) as DeliveryJob;
    const attempt = Number(record.attributes.ApproximateReceiveCount);
    const base = { webhookId: job.webhookId, subscriberId: job.subscriberId, attempt };

    const secret = await deps.getSecret(job.subscriberId);
    const result = await deps.send(job, secret);

    if (result.kind === 'delivered') {
      log({ ...base, outcome: 'delivered', status: result.status });
      return true;
    }
    if (result.kind === 'gone') {
      // 410 Gone: the receiver does not want any more webhooks
      await deps.disableSubscription(job);
      log({ ...base, outcome: 'disabled' });
      return true;
    }
    if (attempt >= deps.maxAttempts) {
      // Last attempt: SQS will move the message to the DLQ next
      log({ ...base, outcome: 'exhausted', reason: result.reason });
      return false;
    }
    const delay = result.retryAfterSeconds ?? retryDelaySeconds(attempt, deps.random);
    await deps.delayMessage(record.receiptHandle, delay);
    log({ ...base, outcome: 'retry', reason: result.reason, delaySeconds: delay });
    return false;
  }

  return async (event: SQSEvent): Promise<SQSBatchResponse> => {
    const results = await Promise.allSettled(event.Records.map(processRecord));
    const batchItemFailures = results.flatMap((result, i) => {
      const ok = result.status === 'fulfilled' && result.value;
      if (result.status === 'rejected') {
        log({ messageId: event.Records[i].messageId, outcome: 'error', error: String(result.reason) });
      }
      return ok ? [] : [{ itemIdentifier: event.Records[i].messageId }];
    });
    return { batchItemFailures };
  };
}

// Wiring with real AWS clients
const sqs = new SQSClient({});
const ssm = new SSMClient({});
const dynamo = new DynamoDBClient({});
const secretCache = new Map<string, { value: string; expires: number }>();

async function getSecret(subscriberId: string): Promise<string> {
  const cached = secretCache.get(subscriberId);
  if (cached && cached.expires > Date.now()) return cached.value;
  const out = await readParameter(`/kartenkiste/webhooks/${subscriberId}/signing-secret`);
  secretCache.set(subscriberId, { value: out, expires: Date.now() + 5 * 60_000 });
  return out;
}

async function readParameter(name: string): Promise<string> {
  const out = await ssm.send(new GetParameterCommand({ Name: name, WithDecryption: true }));
  const value = out.Parameter?.Value;
  if (!value) throw new Error(`Parameter ${name} is empty`);
  return value;
}

export const handler = createDeliveryHandler({
  maxAttempts: Number(process.env.MAX_ATTEMPTS ?? '8'),
  getSecret,
  send: (job, secret) => sendWebhook(job, secret),
  delayMessage: async (receiptHandle, seconds) => {
    await sqs.send(new ChangeMessageVisibilityCommand({
      QueueUrl: process.env.QUEUE_URL,
      ReceiptHandle: receiptHandle,
      VisibilityTimeout: seconds,
    }));
  },
  disableSubscription: async (job) => {
    await dynamo.send(new UpdateItemCommand({
      TableName: process.env.TABLE_NAME,
      Key: { eventType: { S: job.eventType }, subscriberId: { S: job.subscriberId } },
      UpdateExpression: 'SET enabled = :off, disabledReason = :reason',
      ExpressionAttributeValues: { ':off': { BOOL: false }, ':reason': { S: 'HTTP 410' } },
    }));
  },
});

The dependencies are passed in through createDeliveryHandler, which makes the function testable without AWS. The secrets are stored as SecureString in SSM Parameter Store and cached in memory for five minutes so that not every invocation queries Parameter Store. On the last attempt, the deliverer no longer sets a new delay. SQS then moves the message to the DLQ on the next receive. For other ways to catch errors in asynchronous invocations, see the article on Lambda Destinations.

Step 6: Queue one job per subscriber

The dispatch function is attached to the EventBridge bus. It loads all active subscriptions for the event type and writes one job per subscription into the queue, in batches of at most ten messages, because SendMessageBatch does not allow more.

// src/dispatch.ts
import type { EventBridgeEvent } from 'aws-lambda';
import { DynamoDBClient, QueryCommand, type AttributeValue } from '@aws-sdk/client-dynamodb';
import { SQSClient, SendMessageBatchCommand } from '@aws-sdk/client-sqs';
import type { DeliveryJob } from './deliver.ts';

export interface Subscription {
  subscriberId: string;
  url: string;
}

// One job per subscriber. The webhook-id is derived from the event and the subscriber:
// If the dispatcher runs twice, the receiver gets the same ID and can deduplicate.
export function buildJobs(event: EventBridgeEvent<string, unknown>, subscriptions: Subscription[]): DeliveryJob[] {
  return subscriptions.map((s) => ({
    webhookId: `msg_${event.id}_${s.subscriberId}`,
    subscriberId: s.subscriberId,
    eventType: event['detail-type'],
    url: s.url,
    payload: event.detail,
    occurredAt: event.time,
  }));
}

export function chunk<T>(items: T[], size: number): T[][] {
  const out: T[][] = [];
  for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
  return out;
}

const dynamo = new DynamoDBClient({});
const sqs = new SQSClient({});

async function loadSubscriptions(eventType: string): Promise<Subscription[]> {
  const result: Subscription[] = [];
  let startKey: Record<string, AttributeValue> | undefined;
  do {
    const out = await dynamo.send(new QueryCommand({
      TableName: process.env.TABLE_NAME,
      KeyConditionExpression: 'eventType = :t',
      FilterExpression: 'enabled = :on',
      ExpressionAttributeValues: { ':t': { S: eventType }, ':on': { BOOL: true } },
      ExclusiveStartKey: startKey,
    }));
    for (const item of out.Items ?? []) {
      result.push({ subscriberId: item.subscriberId.S!, url: item.url.S! });
    }
    startKey = out.LastEvaluatedKey;
  } while (startKey);
  return result;
}

export const handler = async (event: EventBridgeEvent<string, unknown>): Promise<void> => {
  const jobs = buildJobs(event, await loadSubscriptions(event['detail-type']));
  for (const batch of chunk(jobs, 10)) {
    const out = await sqs.send(new SendMessageBatchCommand({
      QueueUrl: process.env.QUEUE_URL,
      Entries: batch.map((job, i) => ({ Id: String(i), MessageBody: JSON.stringify(job) })),
    }));
    if (out.Failed?.length) {
      // Throw: EventBridge invokes the function again, the IDs stay the same
      throw new Error(`${out.Failed.length} jobs could not be queued`);
    }
  }
  console.log(JSON.stringify({ eventId: event.id, jobs: jobs.length }));
};

Pay attention to the webhookId. It combines the event ID and the subscriber. EventBridge delivers events at least once, so the dispatch function can run twice. Because the ID stays the same in that case, the receiver recognizes the duplicate. Why duplicate delivery is the normal case is explained in the article on idempotency in AWS Lambda.

Step 7: Infrastructure with the Serverless Framework

This time I use the Serverless Framework for the infrastructure. The file describes both functions, the subscriptions table, the queue with its DLQ and an alarm.

# serverless.yml
service: kartenkiste-webhooks
frameworkVersion: '4'

provider:
  name: aws
  runtime: nodejs22.x
  architecture: arm64
  region: eu-central-1
  memorySize: 256
  logRetentionInDays: 14
  environment:
    TABLE_NAME: !Ref SubscriptionsTable
    QUEUE_URL: !Ref DeliveryQueue
    MAX_ATTEMPTS: '8'
  iam:
    role:
      statements:
        - Effect: Allow
          Action: [dynamodb:Query, dynamodb:UpdateItem]
          Resource: !GetAtt SubscriptionsTable.Arn
        - Effect: Allow
          Action: [sqs:SendMessage, sqs:ChangeMessageVisibility]
          Resource: !GetAtt DeliveryQueue.Arn
        - Effect: Allow
          Action: ssm:GetParameter
          Resource: !Sub arn:aws:ssm:${AWS::Region}:${AWS::AccountId}:parameter/kartenkiste/webhooks/*

functions:
  dispatch:
    handler: src/dispatch.handler
    timeout: 30
    events:
      - eventBridge:
          pattern:
            source: [kartenkiste.shop]
            detail-type: [OrderPaid, OrderRefunded]

  deliver:
    handler: src/handler.handler
    timeout: 30
    events:
      - sqs:
          arn: !GetAtt DeliveryQueue.Arn
          batchSize: 10
          functionResponseType: ReportBatchItemFailures
          maximumConcurrency: 5

resources:
  Resources:
    SubscriptionsTable:
      Type: AWS::DynamoDB::Table
      Properties:
        BillingMode: PAY_PER_REQUEST
        AttributeDefinitions:
          - { AttributeName: eventType, AttributeType: S }
          - { AttributeName: subscriberId, AttributeType: S }
        KeySchema:
          - { AttributeName: eventType, KeyType: HASH }
          - { AttributeName: subscriberId, KeyType: RANGE }

    DeliveryDLQ:
      Type: AWS::SQS::Queue
      Properties:
        MessageRetentionPeriod: 1209600 # 14 days

    DeliveryQueue:
      Type: AWS::SQS::Queue
      Properties:
        VisibilityTimeout: 180          # 6 x Lambda timeout
        MessageRetentionPeriod: 345600  # 4 days
        RedrivePolicy:
          deadLetterTargetArn: !GetAtt DeliveryDLQ.Arn
          maxReceiveCount: 8            # = MAX_ATTEMPTS

    DeliveryDLQAlarm:
      Type: AWS::CloudWatch::Alarm
      Properties:
        AlarmDescription: Webhooks permanently undeliverable
        Namespace: AWS/SQS
        MetricName: ApproximateNumberOfMessagesVisible
        Dimensions:
          - { Name: QueueName, Value: !GetAtt DeliveryDLQ.QueueName }
        Statistic: Maximum
        Period: 300
        EvaluationPeriods: 1
        Threshold: 0
        ComparisonOperator: GreaterThanThreshold
        TreatMissingData: notBreaching

Three values belong together and should always be changed together. At 180 seconds, the queue’s visibility timeout is six times the function timeout, as AWS recommends for SQS triggers. maxReceiveCount and MAX_ATTEMPTS are both set to eight. And the retention period of four days is much longer than the retry window of at most twelve hours. maximumConcurrency also limits how many deliverers run at the same time, so that a large backlog does not flood your partners with requests.

You have to add the sqs:ChangeMessageVisibility permission yourself. For the SQS trigger, the framework only grants the permissions to read and delete. For the secrets, ssm:GetParameter is enough as long as you use the default aws/ssm key. With a customer managed KMS key, you also need kms:Decrypt on that key.

Step 8: Test and deploy

The tests check the signature, the delays, the classification of responses and the behavior of the handler with fake dependencies. Here are the tests for the handler:

// test/handler.test.ts
import { test } from 'node:test';
import assert from 'node:assert/strict';
import type { SQSEvent, SQSRecord } from 'aws-lambda';
import { createDeliveryHandler, type DeliveryDeps } from '../src/handler.ts';
import type { DeliveryResult } from '../src/deliver.ts';

function record(id: string, receiveCount: number): SQSRecord {
  return {
    messageId: id, receiptHandle: `rh-${id}`,
    body: JSON.stringify({ webhookId: `msg_${id}`, subscriberId: 'kasse-nord', eventType: 'OrderPaid', url: 'https://partner.example', payload: {}, occurredAt: '2026-10-29T12:00:00Z' }),
    attributes: { ApproximateReceiveCount: String(receiveCount) } as SQSRecord['attributes'],
    messageAttributes: {}, md5OfBody: '', eventSource: 'aws:sqs', eventSourceARN: 'arn:aws:sqs:eu-central-1:111122223333:q', awsRegion: 'eu-central-1',
  };
}

function setup(results: Record<string, DeliveryResult>) {
  const delays: Array<[string, number]> = [];
  const disabled: string[] = [];
  const deps: DeliveryDeps = {
    maxAttempts: 8,
    getSecret: async () => 'whsec_dGVzdA==',
    send: async (job) => results[job.webhookId],
    delayMessage: async (rh, s) => { delays.push([rh, s]); },
    disableSubscription: async (job) => { disabled.push(job.webhookId); },
    random: () => 1,
    log: () => undefined,
  };
  return { handler: createDeliveryHandler(deps), delays, disabled };
}

test('only failed messages end up in batchItemFailures', async () => {
  const { handler, delays } = setup({
    msg_a: { kind: 'delivered', status: 200 },
    msg_b: { kind: 'retry', reason: 'http:500' },
  });
  const event: SQSEvent = { Records: [record('a', 1), record('b', 3)] };
  assert.deepEqual(await handler(event), { batchItemFailures: [{ itemIdentifier: 'b' }] });
  assert.deepEqual(delays, [['rh-b', 540]]);
});

test('Retry-After takes precedence over the backoff', async () => {
  const { handler, delays } = setup({ msg_a: { kind: 'retry', reason: 'http:429', retryAfterSeconds: 600 } });
  await handler({ Records: [record('a', 1)] });
  assert.deepEqual(delays, [['rh-a', 600]]);
});

test('410 disables the subscription and is not retried', async () => {
  const { handler, disabled } = setup({ msg_a: { kind: 'gone' } });
  assert.deepEqual(await handler({ Records: [record('a', 1)] }), { batchItemFailures: [] });
  assert.deepEqual(disabled, ['msg_a']);
});

test('no new delay on the last attempt, the DLQ takes over', async () => {
  const { handler, delays } = setup({ msg_a: { kind: 'retry', reason: 'network:TypeError' } });
  assert.deepEqual(await handler({ Records: [record('a', 8)] }), { batchItemFailures: [{ itemIdentifier: 'a' }] });
  assert.deepEqual(delays, []);
});

test('unexpected errors only mark the affected message', async () => {
  const { handler } = setup({ msg_a: { kind: 'delivered', status: 200 } });
  const broken = { ...record('x', 1), body: 'not json' };
  assert.deepEqual(await handler({ Records: [record('a', 1), broken] }), { batchItemFailures: [{ itemIdentifier: 'x' }] });
});

npm run typecheck
npm test

You should see output with # pass 19 and # fail 0. After that, deploy and create a test subscriber. A function URL running the receiver from the next section works well as a target.

serverless deploy

# Create the subscriber's secret (32 random bytes)
SECRET="whsec_$(openssl rand -base64 32)"
aws ssm put-parameter --type SecureString \
  --name /kartenkiste/webhooks/kasse-nord/signing-secret --value "$SECRET"

# Add the subscription (take the table name from the output of serverless info)
aws dynamodb put-item --table-name <TABLE> --item '{
  "eventType": {"S": "OrderPaid"}, "subscriberId": {"S": "kasse-nord"},
  "url": {"S": "https://<your-function-url>/"}, "enabled": {"BOOL": true}}'

# Send a test event
aws events put-events --entries '[{"Source":"kartenkiste.shop",
  "DetailType":"OrderPaid","Detail":"{\"orderId\":\"K-1001\"}"}]'

# Follow the deliverer's logs
serverless logs -f deliver --tail

In the deliverer’s log, you will then see a line like {"webhookId":"msg_…_kasse-nord","attempt":1,"outcome":"delivered","status":202}. To try out the retries, let the receiver function return a 503 for a while. Entries with "outcome":"retry" and a delaySeconds value that grows from attempt to attempt will appear.

The receiver side: verify the signature and deduplicate

A webhook is only as secure as the check on the receiving end. If you offer webhooks to partners yourself, give them a short example. This is what a receiver looks like as a Lambda function behind a function URL:

// src/receiver.ts
import type { APIGatewayProxyEventV2, APIGatewayProxyResultV2 } from 'aws-lambda';
import { verifyWebhook } from './signature.ts';

// Example for the other side: a partner receives the webhooks via a function URL
const seen = new Set<string>(); // demo only; use DynamoDB with a condition in production

export const handler = async (event: APIGatewayProxyEventV2): Promise<APIGatewayProxyResultV2> => {
  const body = event.isBase64Encoded
    ? Buffer.from(event.body ?? '', 'base64').toString('utf8')
    : event.body ?? '';
  const id = event.headers['webhook-id'];

  const valid = verifyWebhook({
    secret: process.env.WEBHOOK_SECRET ?? '',
    id,
    timestamp: event.headers['webhook-timestamp'],
    signatureHeader: event.headers['webhook-signature'],
    body,
  });
  if (!valid) return { statusCode: 401 };

  // Duplicate delivery? Just acknowledge it, do not process it again
  if (seen.has(id!)) return { statusCode: 200 };
  seen.add(id!);

  const message = JSON.parse(body) as { type: string; data: unknown };
  console.log(JSON.stringify({ id, type: message.type }));
  // Respond quickly, do the actual work asynchronously
  return { statusCode: 202 };
};

The order is crucial. First, the signature is verified over the raw body, before anything gets parsed. If you parse the JSON first and serialize it again, you often get a slightly different string, and the signature no longer matches. Next comes the duplicate check via webhook-id. The Set in the example only lives as long as the Lambda instance. In real systems, you write the ID to DynamoDB with a condition. I show the complete version, with queue and worker, in Receiving webhooks with Lambda. Finally, the receiver responds quickly with 202 and does the actual work asynchronously so that the sender does not run into a timeout.

Common mistakes with webhook retries

The delay depends on the queue timeout. Without ChangeMessageVisibility, every failed message comes back after three minutes, eight times in a row. After a little more than 20 minutes, it is in the DLQ, even though the partner may only have had an hour of maintenance.

The handler throws an exception. If an unhandled error escapes the handler, the whole batch counts as failed, including the messages that were already delivered. That is why the handler processes each message through Promise.allSettled and only reports the affected IDs.

The webhook-id changes with every attempt. Then the receiver cannot detect duplicates. The ID belongs to the event and the subscriber, not to the individual HTTP call.

Throttling counts too. ApproximateReceiveCount increases with every receive, including when Lambda could not process a message due to missing capacity. If you limit concurrency very tightly, messages can end up in the DLQ sooner than expected. The AWS recommendation of a sixfold visibility timeout gives you some headroom here.

Nobody looks at the DLQ. A dead-letter queue without an alarm is a trash can. Connect the alarm to an SNS topic or your chat channel, and plan to move the messages back to the main queue after an outage using the “redrive” feature in the SQS console.

Costs and security

The costs of webhook retries are moderate with this pattern. Every SQS action counts as a request, including ChangeMessageVisibility, and according to AWS one million requests per month are free. A webhook with three failed attempts generates roughly a dozen requests for sending, receiving, visibility and deleting. With Lambda, you mainly pay for the time the deliverer waits for the partner. If you want to work out what that means for your volume, the Lambda cost calculator helps.

Security: watch out for SSRF

On the security side, there is one point that is often overlooked: if partners enter their URL themselves, someone can also register an internal address, such as http://169.254.169.254/ or an IP from your VPC. This kind of attack is called server-side request forgery (SSRF). Therefore, only allow HTTPS URLs, check at registration time that the hostname does not resolve to private or link-local addresses, and run the deliverer without a VPC attachment so it cannot reach internal systems in the first place.

Signing secrets belong neither in the subscriptions table nor in environment variables. In Parameter Store they are encrypted, and the IAM role may only read parameters under /kartenkiste/webhooks/. To rotate a key, create the new secret, sign with both for a while and remove the old one afterwards.

My take

I consider webhooks one of the most underestimated integration patterns. They look trivial, and that is exactly why they often get written into a controller on the side. Yet a webhook is a promise to a partner: “You will hear about it when something changes.” If you keep that promise with a single HTTP call, you only keep it on good days.

The solution with SQS and ChangeMessageVisibility is, for me, the best trade-off between effort and reliability. You need no workflow service, no database for the delivery status and no cron job collecting stuck jobs. The queue is the state. Where I deliberately disagree: some vendors retry for days, and the specification gives an example spanning about three days. For order and status events, I find that too long. After twelve hours, the information is often outdated, and a human should look at the problem. If your partners need a longer window, increase the number of attempts and the queue’s retention period.

What this pattern does not guarantee

What this pattern does not provide is a guarantee about ordering. A refunded order can reach the partner before the payment confirmation if the first message is stuck in a delay. Receivers should therefore work with the timestamp in the body or fetch the current state through an API when needed.

FAQ

How often should you retry a webhook?

There is no fixed standard for webhook retries. Five to ten attempts with exponentially growing delays over a few hours to a few days are common. More important than the exact number is that delays include a random component and that failed messages land in a DLQ with an alarm.

Which HTTP status codes should trigger a retry?

Timeouts, network errors, 429 and all 5xx codes should always be retried. According to the Standard Webhooks specification, any response outside 2xx counts as a failure. 410 Gone is the exception: the receiver no longer wants messages, and the subscription gets disabled.

How do you prevent a webhook from being processed twice?

The sender sends the same webhook-id with every attempt. The receiver stores processed IDs, for example with a conditional write in DynamoDB, and acknowledges duplicates with 200 without processing them again.

How do you verify a webhook signature?

The receiver computes an HMAC-SHA256 over ID, timestamp and raw body with the shared secret and compares it with the header in constant time. In addition, it rejects messages whose timestamp differs from the current time by more than a few minutes.

Your next step

Take a look at how your application sends webhooks or other calls to external systems today. If the call sits directly in the request path, that is the first candidate for a queue with webhook retries. You do not have to rebuild everything at once: an SQS queue with a DLQ and an alarm already prevents events from silently disappearing. You can add backoff and signatures afterwards.

I am curious how you handle this: how long do you retry webhooks, and what do you do with partners that are permanently unreachable? Feel free to share it in the comments.

More in this series: Previous part: DynamoDB TTL: build seat holds that expire · Next part: Receiving webhooks with Lambda: signatures, duplicates, SQS · All parts of the series “Serverless patterns in practice”

Sources

This post was created with AI assistance.

👉 Next step: Curious what your own Lambda functions cost? Try my Lambda cost calculator – it runs right in your browser.

Originally published on sascha-ms.de. More articles on serverless, AI in everyday development and leading tech teams: sascha-ms.de/en

Offboarding checklist: when someone leaves the team

Sascha Mirow-Stanitzok — Sun, 01 Nov 2026 12:54:02 +0000

A good offboarding checklist helps you at exactly the moment you are least prepared for as a leader: someone on your team asks for a quick chat, closes the door and tells you they are leaving. The next few weeks decide whether the team feels this departure as a hole or as a cleanly passed baton.

This topic matters to me because many teams now take onboarding seriously, while its counterpart is almost always improvised. Yet just as much happens when someone leaves: knowledge walks out the door, roles open up, and the team watches very closely how a person who is not staying gets treated. This guide gives you a four-phase process, a knowledge inventory, exit interview questions and a complete checklist.

In short

Offboarding is a leadership task, not an HR form: how you handle a departure shapes the trust of the people who stay. Pass on knowledge in handover pairs, not piles of documents. The biggest obstacle is time: the last weeks are always shorter than you think.

What you will learn in this article

How to respond in the first conversation after a resignation
In which order to inform the team and stakeholders
How a knowledge inventory with handover pairs works
Which questions belong in the exit interview and who should run it
How the team reassigns roles after someone leaves

Why offboarding is a leadership task

Many teams treat a departure as an administrative process. HR, return the laptop, revoke access, done. That is necessary, but it is not enough. For your team, a departure is a social event. People wonder why someone is leaving, who will take over the work and whether they missed something themselves.

It is also worth taking an honest look at the numbers. In 2019, Gallup surveyed people who had voluntarily left their jobs. 52 percent said that their boss or their company might have been able to keep them. And 51 percent reported that nobody had spoken with them about how satisfied they were or where they were heading during their final three months. The study comes from the US, so I would not transfer the percentages one to one. Still, the direction is clear to me: many departures announce themselves, but nobody asks. How to have these conversations while there is still time is covered in the guide to the stay interview.

So offboarding really starts before the resignation, namely in your recurring one-on-ones. Once the decision has been made, though, the focus shifts, and that is exactly what an offboarding checklist is for: a good farewell for the person, a clean handover for the team and a few lessons for you.

The four phases of offboarding from the resignation to the team retro

The first 48 hours after a resignation

The first two days set the tone for everything that follows. During this time you want to achieve three things: show the person that you respect their decision, agree on a rough schedule and decide who finds out when.

The first conversation: listen instead of persuading

The first reaction is often a reflex. Some leaders go quiet, others immediately start negotiating. Neither helps much. Thank the person for being open, ask follow-up questions if they want to talk, and give them space if they don’t. A sentence like “Thanks for telling me directly. Would you like to share how this came about?” is all you need.

Avoid questions that sound like an interrogation, and don’t make promises you can’t keep. By the end of the conversation only two things need to be settled: you will meet again in the next few days to plan, and until then the news stays between the two of you (and HR, if that is how things work in your company).

Announcing it to the team

GitLab, for example, describes a good process in its public handbook: for voluntary departures, the person and their manager review the message together first. The direct team hears it first, then the key stakeholders, and only then the wider group. I think this order is right. Nothing is more awkward for a team than hearing about a departure from another department.

The person should be allowed to decide whether to tell the team themselves or whether you do it. What matters is that the announcement contains more than “X is leaving us”, namely a first sentence about the plan: when the last day is and that you will tackle the handover together. That takes the energy out of the rumor mill. This is why the announcement sits at the top of my offboarding checklist.

Separations initiated by the company follow different rules. There, HR and legal usually take the lead, communication is brief, and details don’t belong in the team. This guide focuses on voluntary departures.

Offboarding checklist for the knowledge handover

The biggest mistake in knowledge transfer is the sentence “Please write everything down.” The result is a long document that nobody reads, written under time pressure by someone whose mind is already halfway elsewhere. An offboarding checklist with two steps works better: first an inventory, then targeted handovers.

Step 1: a knowledge inventory in 45 minutes

Sit down with the person and go through these areas together. For each item, note whether it needs a handover and to whom.

Area	Guiding question	Result
Tasks	What is running right now, what is half done?	List with a new owner
Recurring work	What happens monthly, quarterly, yearly?	Dates in the team calendar
Contacts	Who calls you when something is on fire?	Introduction of the successor
Knowledge in your head	What do only you know?	Candidates for handover pairs
Access and ownership	Who owns documents, channels, repositories?	Transfer ownership

The question “What do only you know?” is the most important one in the whole table. It shows you where your team has a bus factor of one. The bus factor describes how many people would have to drop out before a topic comes to a standstill. At one, it is exactly this person.

Step 2: handover pairs instead of piles of documents

For every topic in the “Knowledge in your head” column, you form a pair: the person leaving and someone who takes over. The two of them work through real tasks together, first with the leaving person in the lead, then with the roles switched. Only what comes up during this joint work gets documented. These notes are shorter and much more useful than a farewell document.

Schedule fixed slots for this, for example two blocks per week. Without a fixed slot, day-to-day business always wins. Also make sure not to dump everything on a single person in the team. Otherwise you are only moving the bus factor around.

What cannot be handed over

Relationships, experience and gut feeling cannot be passed on completely. That is fine. Tell your team honestly that some things will run more slowly after the departure, and plan buffer time for it. Pretending that everything is back to normal after three handover sessions puts unnecessary pressure on the successors.

Counteroffer or letting go?

I have a clear opinion here: a last-minute counteroffer is almost always a band-aid. When someone resigns, salary is rarely the only reason. Usually it is about prospects, tasks, collaboration or leadership. A higher offer changes none of that, it only postpones the question by a few months.

There are exceptions, for instance when a clear, solvable reason is on the table that you simply didn’t know about before. Then you may ask whether a change would make a difference. Pressure or guilt, however, have no place in this conversation. The more honest consequence is usually a different one: listen earlier, so it doesn’t get that far in the first place.

The exit interview: questions that actually reveal something

An exit interview is a structured conversation in the last days, in which the leaving person gives feedback on the team, the work and leadership. A case study by Everett Spain and Boris Groysberg in Harvard Business Review shows how much such conversations can achieve: a financial services company had hired a new manager for 17 people, and after one year only eight of them were still on the team. The exit interviews revealed weaknesses of this one manager and, behind that, a pattern in the system: promotions were based on technical skills instead of leadership skills. The company then changed its promotion process.

Who should run the conversation

If you are the direct manager, you will rarely get the whole truth. That is human, because nobody wants to burn bridges on the way out. It is better if someone outside the direct reporting line runs the conversation, such as HR or a leader from another area. You can additionally hold a personal closing conversation, which can be warmer.

Questions for the exit interview

These questions work well because they are concrete and forward-looking:

When did you first seriously think about leaving, and what was going on at the time?
Could anything have made you stay, and if so, what?
Which things should the team never change?
What would you advise your successor in their first week?
What feedback would you still like to give me as a leader?

Write down the answers and read them side by side after three or four departures. Individual statements are opinions, recurring statements are signals.

Access, reference letter and formalities

Even if the human part matters more, the formal part belongs on every offboarding checklist. Clarify early with HR who takes care of what.

Access to systems, repositories and communication channels should reliably end on the last day. GitLab’s handbook, for example, names 24 hours as the target for critical tools. If you use AWS IAM Identity Center, you can even automate the removal of permissions, as I show in Identity Center EventBridge: automating offboarding. This also includes transferring ownership of documents, calendars and channels beforehand so that nothing is orphaned.

In Germany, there is also the reference letter (Arbeitszeugnis). Under Section 109 of the German Trade Regulation Act (Gewerbeordnung), employees are entitled to a written reference when their employment ends, on request including statements about performance and conduct. It must be clear and understandable and must not contain hidden messages. Other countries have different rules, and HR usually handles the process. I am not a lawyer, so if in doubt, ask them. Your contribution as a leader is an honest, concrete assessment that is not written at the last minute.

Shaping the farewell, remote too

A farewell doesn’t have to be big, but it should happen. A last team breakfast, a short round on a video call where everyone says one sentence, or a digital card. Remotely, it is especially easy for someone to simply go offline on their last day and that’s it. That feels wrong for both sides.

Also talk about how you will stay in touch. Some companies have alumni networks, in others a profile on a professional network is enough. People who leave on good terms recommend you or eventually come back. You want to keep that door open.

What the team learns after a departure

A few weeks after the last day, a short team retrospective is worth it, meaning a moderated session for looking back. The focus is on the team and its work. These questions help:

Which tasks have been left undone since the departure?
Where are we missing knowledge that we didn’t miss before?
Which roles do we need to reassign, and who would like to take something on?
What will we do differently next time someone leaves?

Use the opportunity to consciously reassign responsibility, too. The levels of delegation help you agree with each person on how much decision-making room they get for a new topic. Add the answers to question 4 directly to your offboarding checklist. And when a successor is hired, the circle closes with good onboarding for the first 30 days.

Common offboarding mistakes

Some patterns keep showing up, and an offboarding checklist helps you avoid them:

The handover only starts in the last week because there is “still so much to do” before that.
The team hears about the departure indirectly instead of directly.
All the knowledge ends up with the one person who already carries the most.
The exit interview happens, but nobody ever reads the notes again.
On the last day, nobody is there to say thank you.

The complete offboarding checklist

To tick off, from the resignation to after the last day:

First conversation held, thanks said, next meeting scheduled
Process clarified with HR (last day, remaining vacation, reference letter)
Announcement written together: first the team, then stakeholders, then the wider group
Knowledge inventory done and handover pairs formed with fixed slots
Recurring tasks and meetings reassigned, ownership transferred
Exit interview planned with a neutral person
Farewell organized and a way to stay in touch agreed
Access removed on the last day and verified
Team retrospective held after a few weeks

FAQ

How long does good offboarding take?

Ideally, as long as the notice period. Plan the knowledge handover for the first two weeks, because remaining vacation, the farewell and formalities pile up in the last days. With short notice periods, the phases run in parallel.

Who is responsible for offboarding?

Formal matters such as contracts, the reference letter and hardware usually lie with HR and IT. The handover, communication within the team and the farewell are the job of the direct manager.

Should the manager run the exit interview themselves?

Preferably not alone. Many people speak less openly with their direct manager on their way out. A neutral person from HR or another area often gets more honest answers.

What belongs in an offboarding checklist for managers?

The first conversation, the order of the announcement, a knowledge inventory with handover pairs, the exit interview, access and the reference letter, a farewell and a team retrospective afterwards.

Your next step

You don’t have to wait for someone to resign to use the offboarding checklist. Take the “What do only you know?” question from the knowledge inventory and go through it with your team this week, without any occasion. Every topic with a bus factor of one is a candidate for a handover pair, and that means now, not during the notice period.

How does it work for you: is there a fixed process in your team when someone leaves, or do you improvise every time? Feel free to share it in the comments.

Continue the series: Back to the “Leadership in brief” overview · Previous part: Remote onboarding: planning the first 30 days. Next part: Stay interview: holding stay conversations.

Sources

This post was created with AI assistance.

👉 Next step: Preparing a first one-on-one? My question cheat sheet puts the best questions on one printable page.

Originally published on sascha-ms.de. More articles on serverless, AI in everyday development and leading tech teams: sascha-ms.de/en

Identity Center EventBridge: automate offboarding

Sascha Mirow-Stanitzok — Sun, 01 Nov 2026 12:22:03 +0000

Identity Center EventBridge integration is something many teams have probably been waiting for: as of this week, IAM Identity Center emits an event whenever a user, a group or a group membership is created, updated or deleted in the Identity Store. You can now react to changes instead of polling for them with a script. What interests me most is offboarding, because access that lingers for days after someone switches teams or leaves the company is a classic finding in every security audit.

In this article you will build a small Serverless application that handles exactly that. A Lambda function listens to identity events, checks the current state in the Identity Store and then maintains the access list of your own application. A nightly reconciliation catches whatever slips through the cracks. You describe the infrastructure with the Serverless Framework, and the code is TypeScript.

In short

Identity Center now sends events such as “GroupMembership Deleted” to the EventBridge default bus, in the account and Region of your Identity Center instance. The events only contain IDs, no names or email addresses. The biggest pitfall: delivery is at least once and unordered, so decide based on the current state and reconcile regularly.

What you will learn in this article

Which events IAM Identity Center sends to EventBridge and what they contain
Why an event is only a trigger and not the source of truth
An EventBridge rule with Lambda, retries and a failure queue in the Serverless Framework
How to revoke access idempotently and reconcile desired vs. actual state every night
Which account and Region you have to deploy to

What is new with Identity Center and EventBridge?

A quick bit of context: IAM Identity Center is the AWS service for central sign-in (single sign-on) to AWS accounts and applications. Users and groups live in the Identity Store, a directory that you either maintain directly in Identity Center or populate from an external identity provider via SCIM. SCIM is a standard protocol that lets an identity provider push users and groups to other systems automatically.

Until now, reacting to changes meant either polling the Identity Store API on a schedule or digging through CloudTrail records. Since October 28, 2026, the Identity Store delivers its own events to Amazon EventBridge, the AWS event bus. According to the announcement there is no extra cost beyond regular EventBridge charges, and the feature is available in every Region that offers Identity Center. There is nothing to switch on: as soon as a rule with a matching pattern and a target exist, the events start flowing.

Event (detail-type)	When it is sent
`User Created`, `User Updated`, `User Deleted`	A user is created, changed or deleted
`Group Created`, `Group Updated`, `Group Deleted`	A group is created, changed or deleted
`GroupMembership Created`, `GroupMembership Deleted`	A user joins a group or gets removed from it
`IdentityStore Created`, `…Updated`, `…Deleted`	The Identity Store itself changes, for instance when you enable Identity Center

All events share the source aws.identitystore, and the event name sits in the detail-type field. Here is what an event looks like according to the AWS documentation, slightly shortened:

{
  "version": "0",
  "id": "c22ba61f-32ac-42f1-a59b-f7f667b428ab",
  "detail-type": "User Updated",
  "source": "aws.identitystore",
  "account": "111122223333",
  "time": "2026-01-02T11:59:59Z",
  "region": "us-west-2",
  "resources": [
    "arn:aws:identitystore::111122223333:identitystore/d-1234567890",
    "arn:aws:identitystore:::user/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
  ],
  "detail": {
    "event-version": "0.1",
    "request-id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
    "identity-store": { "id": "d-1234567890" },
    "user": { "id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111" }
  }
}

What the event does not tell you

Notice what is missing from Identity Center events on EventBridge: no names, no email addresses, no group names. A User Updated event does not even reveal which attribute changed. From a privacy point of view that makes sense, since no personal data ends up in event archives or logs. For you, however, it means you always fetch details through the Identity Store API, for example with DescribeUser.

On top of that, the documentation lists three properties that shape your design. Events arrive at least once, so duplicates are possible. Ordering is not guaranteed, and neither is a maximum delivery time. AWS therefore explicitly recommends checking the current state through the API and reconciling downstream systems periodically. That is exactly how we will build it.

Which account and Region receive the events

Identity Center events land on the EventBridge default bus in the Region in which you activated Identity Center. With an organization instance, the account is the management account of your AWS Organization; for an account instance, it is the member account in which you turned on Identity Center. If you replicated the instance to more Regions, the same event shows up in each of them. Anyone who creates a rule in every one of those Regions will process each change several times.

The example: a recipe book with its own access list

To make this tangible, picture a fictional bakery with several branches. It runs a small internal web application, the “recipe book”. Sign-in goes through Identity Center, but the recipe book also keeps its own access list in DynamoDB: whoever is on it may view and edit recipes. Secondary lists like this are everywhere in practice, for licenses, for roles inside an application or for accounts in a third-party system.

The rule is simple: anyone in the Identity Center group recipe-book-users belongs on the access list. Anyone who leaves the group or gets deleted is removed, promptly rather than at the next quarterly review.

The event function reacts immediately, while the nightly reconciliation catches missed or delayed events.

Why Identity Center events alone are not enough

The obvious idea would be: add an entry on GroupMembership Created and delete it on GroupMembership Deleted. That works as long as everything arrives in the right order and exactly once. Now imagine an admin accidentally removes a user from the group and adds her back a minute later. If the two events arrive swapped, the deletion wins. According to Identity Center the user is entitled, yet the recipe book locks her out.

That is why I treat the event only as a hint that something changed for this person. The function then calls IsMemberInGroups to check whether the person is in the group right now and brings the access list in line with that state. This approach is idempotent by nature: no matter how often or in what order events arrive, the result always matches the current state in the Identity Store. Idempotent means that running an operation several times gives the same result as running it once.

🎬 How the function reacts to an identity event – this animated diagram only runs on my site: watch it on sascha-ms.de

The second building block is a nightly reconciliation of desired versus actual state. It lists all members of the group, compares them with the access list and fixes any differences. That sounds like double work, but it is your insurance against everything you cannot foresee: a rule that was misconfigured for an hour, a deployment at the wrong moment or an event that simply never arrives. The pattern “events for speed, reconciliation for correctness” has proven itself in event-driven systems, and not only for identities.

Step by step: connecting Identity Center EventBridge events to Lambda

Prerequisites

An AWS account with IAM Identity Center enabled and at least one test group and one test user
Access to the account that receives the events (see above), with permissions for CloudFormation, Lambda, DynamoDB, SQS, EventBridge and IAM
Node.js 22 and AWS CLI v2
Serverless Framework v4 (npm i -g serverless); v4 asks you to log in or provide a license key on first use, and it is free for small organizations

A note up front: with an organization instance, events arrive in the management account. You normally do not want to run workloads there. For a first test that is acceptable, but later you should forward the events with a rule to a bus in a dedicated security or tooling account. You will find how to do that further down in the section on common mistakes.

Step 1: find the Identity Store ID and the group ID

In the CLI, switch to the Region of your Identity Center instance. The Identity Store ID starts with d-:

aws sso-admin list-instances --region eu-central-1 \
  --query 'Instances[0].IdentityStoreId' --output text

aws identitystore get-group-id --region eu-central-1 \
  --identity-store-id d-1234567890 \
  --alternate-identifier '{"UniqueAttribute":{"AttributePath":"displayName","AttributeValue":"recipe-book-users"}}'

Expected result: an ID such as d-1234567890 and a response with a GroupId. You need both values for the deployment.

Step 2: create the project

mkdir recipe-book-access && cd recipe-book-access
npm init -y
npm i @aws-sdk/client-identitystore @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
npm i -D typescript @types/node @types/aws-lambda
mkdir src test

The package.json gets two scripts and the ES module format:

{
  "name": "identity-center-offboarding",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "typecheck": "tsc --noEmit",
    "test": "node --test --experimental-strip-types test/*.test.ts"
  },
  "dependencies": {
    "@aws-sdk/client-dynamodb": "^3.1159.0",
    "@aws-sdk/client-identitystore": "^3.1159.0",
    "@aws-sdk/lib-dynamodb": "^3.1159.0"
  },
  "devDependencies": {
    "@types/aws-lambda": "^8.10.164",
    "@types/node": "^22.18.0",
    "typescript": "^7.0.2"
  }
}

{
  "compilerOptions": {
    "target": "ES2023",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "types": ["node"],
    "skipLibCheck": true
  },
  "include": ["src", "test"]
}

Serverless Framework v4 handles the build itself with esbuild. You only use TypeScript for type checking, and the tests run directly on Node.js.

Step 3: parse the event

The first file turns the raw event into a small, easily testable object. The documentation only shows the full format for User Updated and states that membership events also carry the user and group IDs. So I read the IDs from detail and otherwise fall back to the ARNs in the resources field. During your first test, log a real membership event and verify the field names before you go to production.

// src/identity-event.ts
import type { EventBridgeEvent } from 'aws-lambda';

export type IdentityDetailType =
  | 'User Created' | 'User Updated' | 'User Deleted'
  | 'Group Created' | 'Group Updated' | 'Group Deleted'
  | 'GroupMembership Created' | 'GroupMembership Deleted'
  | 'IdentityStore Created' | 'IdentityStore Updated' | 'IdentityStore Deleted';

export interface IdentityDetail {
  'event-version'?: string;
  'request-id'?: string;
  'identity-store'?: { id?: string };
  user?: { id?: string };
  group?: { id?: string };
}

export type IdentityEvent = EventBridgeEvent<IdentityDetailType, IdentityDetail>;

export interface ParsedChange {
  eventId: string;
  type: IdentityDetailType;
  identityStoreId?: string;
  userId?: string;
  groupId?: string;
}

// Extracts an ID from the resources array, e.g. ".../user/<id>"
function idFromResources(resources: string[], kind: 'user' | 'group'): string | undefined {
  const match = resources
    .map((arn) => new RegExp(`:${kind}/([^/]+)$`).exec(arn))
    .find((m) => m !== null);
  return match?.[1];
}

export function parseIdentityEvent(event: IdentityEvent): ParsedChange {
  if (event.source !== 'aws.identitystore') {
    throw new Error(`Unexpected source: ${event.source}`);
  }
  const detail = event.detail ?? {};
  const resources = event.resources ?? [];
  return {
    eventId: event.id,
    type: event['detail-type'],
    identityStoreId: detail['identity-store']?.id,
    userId: detail.user?.id ?? idFromResources(resources, 'user'),
    groupId: detail.group?.id ?? idFromResources(resources, 'group'),
  };
}

Step 4: the decision as a pure function

The actual logic lives in a function without any AWS calls. It takes the event type, the IDs and the current membership status and returns one of four actions. If the user ID is missing, it triggers a full reconciliation rather than guessing. The file also contains the diff calculation for the nightly run.

// src/access.ts
export type Action = 'grant' | 'revoke' | 'reconcile' | 'ignore';

// Decides what to do based on the event AND the current state.
// isMember is undefined if the state could not be queried.
export function decideAction(input: {
  type: string;
  userId?: string;
  groupId?: string;
  targetGroupId: string;
  isMember?: boolean;
}): Action {
  const { type, userId, groupId, targetGroupId, isMember } = input;

  if (type === 'User Deleted') return userId ? 'revoke' : 'reconcile';

  if (type === 'GroupMembership Created' || type === 'GroupMembership Deleted') {
    if (!userId) return 'reconcile';
    if (groupId && groupId !== targetGroupId) return 'ignore';
    if (isMember === undefined) return 'reconcile';
    return isMember ? 'grant' : 'revoke';
  }

  if (type === 'Group Deleted' && groupId === targetGroupId) return 'reconcile';
  return 'ignore';
}

// Compares desired state (group members) with actual state (access table).
export function planChanges(members: Iterable<string>, withAccess: Iterable<string>) {
  const should = new Set(members);
  const has = new Set(withAccess);
  return {
    grant: [...should].filter((id) => !has.has(id)).sort(),
    revoke: [...has].filter((id) => !should.has(id)).sort(),
  };
}

Step 5: talk to the Identity Store and DynamoDB

All AWS calls live here. Two details matter. First, grantAccess uses DescribeUser to check that the person still exists and, while at it, loads the user name and email for display in the recipe book. Second, recordOnce writes the audit entry with a condition, so a duplicate event produces only one entry. The expiresAt attribute lets DynamoDB TTL remove audit entries automatically after 90 days.

// src/store.ts
import {
  IdentitystoreClient,
  IsMemberInGroupsCommand,
  DescribeUserCommand,
  ResourceNotFoundException,
  paginateListGroupMemberships,
} from '@aws-sdk/client-identitystore';
import { DynamoDBClient, ConditionalCheckFailedException } from '@aws-sdk/client-dynamodb';
import {
  DynamoDBDocumentClient,
  PutCommand,
  DeleteCommand,
  paginateScan,
} from '@aws-sdk/lib-dynamodb';

const ids = new IdentitystoreClient({});
const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Environment variable ${name} is missing`);
  return value;
}

export const config = {
  get identityStoreId() { return env('IDENTITY_STORE_ID'); },
  get groupId() { return env('TARGET_GROUP_ID'); },
  get accessTable() { return env('ACCESS_TABLE'); },
  get auditTable() { return env('AUDIT_TABLE'); },
};

export async function isMemberOfTargetGroup(userId: string): Promise<boolean> {
  const out = await ids.send(new IsMemberInGroupsCommand({
    IdentityStoreId: config.identityStoreId,
    MemberId: { UserId: userId },
    GroupIds: [config.groupId],
  }));
  return out.Results?.some((r) => r.GroupId === config.groupId && r.MembershipExists) ?? false;
}

export async function listTargetGroupMembers(): Promise<string[]> {
  const members: string[] = [];
  const pages = paginateListGroupMemberships(
    { client: ids },
    { IdentityStoreId: config.identityStoreId, GroupId: config.groupId },
  );
  for await (const page of pages) {
    for (const m of page.GroupMemberships ?? []) {
      if (m.MemberId && 'UserId' in m.MemberId && m.MemberId.UserId) {
        members.push(m.MemberId.UserId);
      }
    }
  }
  return members;
}

export async function listUsersWithAccess(): Promise<string[]> {
  const users: string[] = [];
  const pages = paginateScan(
    { client: ddb },
    { TableName: config.accessTable, ProjectionExpression: 'userId' },
  );
  for await (const page of pages) {
    for (const item of page.Items ?? []) users.push(String(item.userId));
  }
  return users;
}

export async function grantAccess(userId: string): Promise<boolean> {
  try {
    const user = await ids.send(new DescribeUserCommand({
      IdentityStoreId: config.identityStoreId,
      UserId: userId,
    }));
    await ddb.send(new PutCommand({
      TableName: config.accessTable,
      Item: {
        userId,
        userName: user.UserName,
        email: user.Emails?.find((e) => e.Primary)?.Value ?? user.Emails?.[0]?.Value,
        grantedAt: new Date().toISOString(),
      },
    }));
    return true;
  } catch (err) {
    // User has been deleted in the meantime: nothing to grant
    if (err instanceof ResourceNotFoundException) return false;
    throw err;
  }
}

export async function revokeAccess(userId: string): Promise<void> {
  await ddb.send(new DeleteCommand({ TableName: config.accessTable, Key: { userId } }));
}

// Writes an audit entry exactly once per event ID.
// Returns false if the event was already processed.
export async function recordOnce(entry: {
  eventId: string; action: string; userId?: string; type: string;
}): Promise<boolean> {
  const ninetyDays = 90 * 24 * 60 * 60;
  try {
    await ddb.send(new PutCommand({
      TableName: config.auditTable,
      Item: {
        ...entry,
        processedAt: new Date().toISOString(),
        expiresAt: Math.floor(Date.now() / 1000) + ninetyDays,
      },
      ConditionExpression: 'attribute_not_exists(eventId)',
    }));
    return true;
  } catch (err) {
    if (err instanceof ConditionalCheckFailedException) return false;
    throw err;
  }
}

Step 6: handler and nightly reconciliation

The handler wires the pieces together. It acts first and records afterwards. That order is deliberate: if recording fails, Lambda retries the invocation, and repeating the action does not change the outcome. The other way round, an event could be marked as done while the access still exists.

// src/handler.ts
import { parseIdentityEvent, type IdentityEvent } from './identity-event.ts';
import { decideAction } from './access.ts';
import { reconcileAll } from './reconcile.ts';
import {
  config, grantAccess, revokeAccess, isMemberOfTargetGroup, recordOnce,
} from './store.ts';

export const handler = async (event: IdentityEvent): Promise<void> => {
  const change = parseIdentityEvent(event);
  if (change.identityStoreId && change.identityStoreId !== config.identityStoreId) {
    console.warn(JSON.stringify({ msg: 'Foreign identity store', eventId: change.eventId }));
    return;
  }

  const needsState = change.type.startsWith('GroupMembership') && change.userId;
  const isMember = needsState ? await isMemberOfTargetGroup(change.userId!) : undefined;

  const action = decideAction({
    type: change.type,
    userId: change.userId,
    groupId: change.groupId,
    targetGroupId: config.groupId,
    isMember,
  });

  if (action === 'ignore') return;

  if (action === 'grant') await grantAccess(change.userId!);
  if (action === 'revoke') await revokeAccess(change.userId!);
  if (action === 'reconcile') await reconcileAll();

  // Act first, then record: a duplicate event does not change the outcome
  const firstTime = await recordOnce({
    eventId: change.eventId, action, userId: change.userId, type: change.type,
  });
  console.log(JSON.stringify({
    msg: 'Identity event processed', eventId: change.eventId,
    type: change.type, action, duplicate: !firstTime,
  }));
};

// src/reconcile.ts
import { planChanges } from './access.ts';
import {
  grantAccess, revokeAccess, listTargetGroupMembers, listUsersWithAccess,
} from './store.ts';

export async function reconcileAll(): Promise<{ granted: number; revoked: number }> {
  const [members, withAccess] = await Promise.all([
    listTargetGroupMembers(),
    listUsersWithAccess(),
  ]);
  const plan = planChanges(members, withAccess);
  let granted = 0;
  for (const userId of plan.grant) {
    if (await grantAccess(userId)) granted++;
  }
  for (const userId of plan.revoke) await revokeAccess(userId);
  return { granted, revoked: plan.revoke.length };
}

// Invoked nightly by a schedule
export const handler = async (): Promise<void> => {
  const result = await reconcileAll();
  console.log(JSON.stringify({ msg: 'Reconciliation finished', ...result }));
};

Step 7: the serverless.yml

The rule on the EventBridge default bus listens only for the four Identity Center events that matter to the recipe book. If delivery to Lambda fails, EventBridge retries up to five times within an hour and then puts the event into the failure queue. If, on the other hand, the function itself fails after Lambda’s asynchronous retries, the event lands in the same queue via the Lambda destination onFailure. A CloudWatch alarm fires as soon as anything shows up there. By the way, the specific event names in the pattern are mandatory: CloudTrail forwards Identity Store API calls to EventBridge under the very same source aws.identitystore, using the detail-type AWS API Call via CloudTrail. Without that filter, the function would run on every API call.

# serverless.yml
service: recipe-book-access
frameworkVersion: '4'

provider:
  name: aws
  runtime: nodejs22.x
  architecture: arm64
  region: ${opt:region, 'eu-central-1'}
  memorySize: 256
  timeout: 30
  logRetentionInDays: 30
  environment:
    IDENTITY_STORE_ID: ${param:identityStoreId}
    TARGET_GROUP_ID: ${param:targetGroupId}
    ACCESS_TABLE: !Ref AccessTable
    AUDIT_TABLE: !Ref AuditTable
  iam:
    role:
      statements:
        - Effect: Allow
          Action:
            - identitystore:IsMemberInGroups
            - identitystore:DescribeUser
            - identitystore:ListGroupMemberships
          Resource: '*'
        - Effect: Allow
          Action:
            - dynamodb:PutItem
            - dynamodb:DeleteItem
            - dynamodb:Scan
          Resource: !GetAtt AccessTable.Arn
        - Effect: Allow
          Action: dynamodb:PutItem
          Resource: !GetAtt AuditTable.Arn
        - Effect: Allow
          Action: sqs:SendMessage
          Resource: !GetAtt FailedEventsQueue.Arn

functions:
  onIdentityChange:
    handler: src/handler.handler
    reservedConcurrency: 2
    destinations:
      onFailure:
        type: sqs
        arn: !GetAtt FailedEventsQueue.Arn
    events:
      - eventBridge:
          pattern:
            source:
              - aws.identitystore
            detail-type:
              - User Deleted
              - Group Deleted
              - GroupMembership Created
              - GroupMembership Deleted
          retryPolicy:
            maximumEventAge: 3600
            maximumRetryAttempts: 5
          deadLetterQueueArn: !GetAtt FailedEventsQueue.Arn

  nightlyReconcile:
    handler: src/reconcile.handler
    reservedConcurrency: 1
    timeout: 300
    events:
      - schedule:
          rate: cron(15 2 * * ? *)
          enabled: true

resources:
  Resources:
    AccessTable:
      Type: AWS::DynamoDB::Table
      Properties:
        BillingMode: PAY_PER_REQUEST
        AttributeDefinitions:
          - AttributeName: userId
            AttributeType: S
        KeySchema:
          - AttributeName: userId
            KeyType: HASH
        PointInTimeRecoverySpecification:
          PointInTimeRecoveryEnabled: true

    AuditTable:
      Type: AWS::DynamoDB::Table
      Properties:
        BillingMode: PAY_PER_REQUEST
        AttributeDefinitions:
          - AttributeName: eventId
            AttributeType: S
        KeySchema:
          - AttributeName: eventId
            KeyType: HASH
        TimeToLiveSpecification:
          AttributeName: expiresAt
          Enabled: true

    FailedEventsQueue:
      Type: AWS::SQS::Queue
      Properties:
        MessageRetentionPeriod: 1209600

    FailedEventsQueuePolicy:
      Type: AWS::SQS::QueuePolicy
      Properties:
        Queues:
          - !Ref FailedEventsQueue
        PolicyDocument:
          Statement:
            - Effect: Allow
              Principal:
                Service: events.amazonaws.com
              Action: sqs:SendMessage
              Resource: !GetAtt FailedEventsQueue.Arn

    FailedEventsAlarm:
      Type: AWS::CloudWatch::Alarm
      Properties:
        AlarmDescription: Identity events could not be processed
        Namespace: AWS/SQS
        MetricName: ApproximateNumberOfMessagesVisible
        Dimensions:
          - Name: QueueName
            Value: !GetAtt FailedEventsQueue.QueueName
        Statistic: Maximum
        Period: 300
        EvaluationPeriods: 1
        Threshold: 0
        ComparisonOperator: GreaterThanThreshold
        TreatMissingData: notBreaching

The expression cron(15 2 * * ? *) means every day at 02:15 UTC. If you want to check or adjust the syntax, my EventBridge cron explainer helps. The reservedConcurrency limits the function on purpose: a bulk change via SCIM should not flood the Identity Store with hundreds of parallel requests.

Step 8: test and deploy

Start with the local tests and the type check:

npm test
npm run typecheck

Expected result: eight passing tests and no type errors. Then deploy to the Region of your Identity Center instance and pass both IDs as parameters:

serverless deploy --region eu-central-1 \
  --param="identityStoreId=d-1234567890" \
  --param="targetGroupId=<GroupId from step 1>"

After the deployment, wait about a minute and then trigger a real event. Get the user ID of your test user and add the user to the group:

USER_ID=$(aws identitystore get-user-id --region eu-central-1 \
  --identity-store-id d-1234567890 \
  --alternate-identifier '{"UniqueAttribute":{"AttributePath":"userName","AttributeValue":"lena.test"}}' \
  --query UserId --output text)

aws identitystore create-group-membership --region eu-central-1 \
  --identity-store-id d-1234567890 \
  --group-id <GroupId> --member-id UserId=$USER_ID

serverless logs -f onIdentityChange --region eu-central-1 --tail

A line containing "action":"grant" should appear in the log, and the access table should contain an entry for the user ID. Remove the membership again to test revocation:

MEMBERSHIP_ID=$(aws identitystore get-group-membership-id --region eu-central-1 \
  --identity-store-id d-1234567890 \
  --group-id <GroupId> --member-id UserId=$USER_ID \
  --query MembershipId --output text)

aws identitystore delete-group-membership --region eu-central-1 \
  --identity-store-id d-1234567890 --membership-id $MEMBERSHIP_ID

Now the log shows "action":"revoke", and the entry in the access table is gone. You can kick off the nightly reconciliation right away with serverless invoke -f nightlyReconcile.

Common mistakes with Identity Center events

The rule sits in the wrong account or Region

This is the most common reason why nothing arrives with Identity Center and EventBridge. The rule has to live on the default bus of the account and Region where the events are created. If you want to run the processing in another account, create a lean rule in the source account whose target is an event bus in the destination account. That bus needs a resource policy that allows events:PutEvents from the source account. For calling the Identity Store API from another account, have a look at delegated administration for Identity Center in the AWS documentation.

Typos in the event name

EventBridge matches exactly, including case and spaces. GroupMembership Deleted works, Group Membership Deleted does not. A handy trick for getting started: a rule with only "source": ["aws.identitystore"] and a log group as target, so you see every real event in its original form. Do not be surprised if CloudTrail entries show up there too, since they carry the same source.

Relying on the order of events

If you translate Created and Deleted directly into write and delete operations, you will end up with wrong states sooner or later. The IsMemberInGroups check costs one API call per event and spares you a whole class of bugs.

Skipping the reconciliation

The documentation is clear about it: no guaranteed delivery time, and events from before the rule existed are never delivered. Without reconciliation, the access list also stays empty after the first deployment until something changes for every single person. So the first nightly run doubles as the initial load.

Overly broad permissions

For simplicity, the serverless.yml grants the Identity Store actions on Resource: '*'. These permissions are read-only anyway, but for production you should still restrict them to the ARNs of your Identity Store and your group. This solution never needs write access to the Identity Store, and it should stay that way.

Cost and security

For the Identity Center events on EventBridge, AWS names no additional cost beyond the usual EventBridge charges. Lambda and on-demand DynamoDB cost next to nothing for a few hundred changes per month, and the SQS queue is normally empty. The largest item is the nightly scan of the access table, and even that stays in the range of cents for a few thousand entries.

On the security side: the function only reads. It does see user names and email addresses, so that data does not belong in logs. The code deliberately logs only IDs and actions. The audit table contains no names either, and TTL cleans it up after 90 days. Adjust the retention period to your own policies.

My take

I find the combination of Identity Center and EventBridge inconspicuous but valuable. Identities are the part of a cloud environment where late reactions hurt the most. Until now, the answer was often “a script runs every night” or “parse CloudTrail and hope you know every API call”. Now there is a clean, domain-level event with a clear meaning.

At the same time, it is tempting to treat the event stream as the truth. AWS itself warns against exactly that, and I think rightly so. Events are fast, but not reliable in the sense of complete and ordered. Combining both, fast reaction via events and regular reconciliation, gives you a system that heals itself. One drawback remains: with organization instances, everything is tied to the management account. I would have liked direct delivery to a delegated account.

If you are interested in how events, failures and retries play together, also check out my articles on Lambda destinations and EventBridge replay.

Technology only covers part of it. What you can do as a leader when someone leaves your team is described in my offboarding checklist for teams.

FAQ

Do I have to enable Identity Center events somewhere?

No. Identity Center sends the events automatically to the default bus of EventBridge. As soon as a rule with the source aws.identitystore and a target exist, they arrive.

Do changes made via SCIM also produce events?

The documentation talks about changes in the Identity Store in general and does not distinguish by channel. I would try it once with a test rule, a log target and your identity provider before relying on it.

How much do Identity Center events cost?

According to the AWS announcement there is no additional cost beyond regular EventBridge charges. On top of that come the costs of your targets, such as Lambda invocations and DynamoDB writes.

Can I get past changes as events after the fact?

No. Events are only delivered from the moment a matching rule exists, and they are not generated retroactively. For the initial state you need a reconciliation through the Identity Store API.

Your next step

Today, create a single rule with "source": ["aws.identitystore"] and a CloudWatch log group as target, then change a test group. Within five minutes you will see real events from your own environment, and the Lambda function from this article can build on that. Which secondary list in your environment would you hook up to identity events first? Let me know in the comments.

Sources

AWS What’s New: AWS IAM Identity Center’s Identity Store now supports change notifications through Amazon EventBridge (Oct 28, 2026)
IAM Identity Center User Guide: Event notifications
IAM Identity Center User Guide: Set up event notifications
IAM Identity Center User Guide: Receive events in other accounts and Regions
Identity Store API Reference
Serverless Framework: EventBridge Event
Tested with Node.js 22.23, TypeScript 7.0.2, node:test (8 tests), @aws-sdk/client-identitystore, @aws-sdk/client-dynamodb and @aws-sdk/lib-dynamodb 3.1159.0. The resources in the serverless.yml were checked with cfn-lint, not deployed.

This post was created with AI assistance.

👉 Next step: Need a schedule in EventBridge? My EventBridge cron helper builds and explains the expression for you.

Originally published on sascha-ms.de. More articles on serverless, AI in everyday development and leading tech teams: sascha-ms.de/en

SOCI lazy loading: start Lambda containers faster

Sascha Mirow-Stanitzok — Sun, 01 Nov 2026 10:51:05 +0000

SOCI lazy loading lets a Lambda function on Lambda Managed Instances start before its container image has been fully downloaded. AWS announced it on October 28, 2026, and quotes startup times that are up to 70 percent shorter. I care less about that percentage than about two questions: who actually benefits from the extra build step, and where does it cause you trouble?

Container images are often the escape hatch on Lambda for anything that does not fit into a 250 MB ZIP package: ML libraries, models, PDF tools, entire runtimes. Those images quickly grow to several gigabytes. In this article, we build an example from scratch together: a small book recommendation service for a library, an image with four language models, the SOCI index, a CDK stack with a capacity provider and a script that lets you measure the effect yourself.

In short

SOCI places a table of contents next to your container image, so Lambda on Managed Instances only fetches the files your function actually reads. It pays off most for large images where each function needs only part of the content. The biggest pitfall is the format: Lambda accepts only a SOCI index v2 inside an image index with exactly two entries, and only single-architecture images.

What you will learn in this article

What Lambda Managed Instances are and when they fit your workload
How SOCI lazy loading fetches files on demand
How to create a SOCI index with nerdctl and push it to ECR
How to set up a capacity provider and function with AWS CDK in TypeScript
How to measure startup times with and without SOCI yourself

What are Lambda Managed Instances?

Lambda Managed Instances (LMI for short) are a second way to run Lambda functions. Instead of the shared Lambda fleet, your functions run on EC2 instances in your own account. Lambda still takes care of launching, patching, routing and scaling those instances. You only decide where they may run and on which hardware.

The central building block is the capacity provider. It describes the VPC, subnets, security groups, architecture, allowed instance types and an upper limit for vCPUs. You then attach a function to that provider and publish a version. Only when you publish does Lambda launch instances, three by default for spreading across Availability Zones, plus three execution environments, before the version counts as ACTIVE.

How it differs from regular Lambda

	Lambda (default)	Lambda Managed Instances
Invocations per environment	one at a time	several at the same time
Isolation	Firecracker microVMs on a shared fleet	containers on EC2 Nitro instances in your account
Billing	per request and duration	EC2 price plus a 15% management fee
Scaling	on demand, down to zero	asynchronously based on CPU utilization, not to zero
Good fit for	irregular traffic	high, predictable traffic

For Node.js, LMI uses worker threads, and initialization runs once per worker thread. That matters for our example: if you load a large model into memory, expect it to sit in memory once per thread. In addition, concurrent requests in the same thread share the global state. Anything you create outside the handler should therefore only be read and never modified.

If you want to refresh the regular Lambda basics first, my article Deploy a Lambda function with CDK and TypeScript covers the standard path with a ZIP package.

Why large images slow down Managed Instances

Without SOCI, Lambda has to download and unpack the complete image on every instance before an execution environment can start there. That does not happen just once when you publish. It also happens whenever the capacity provider launches new instances because load is rising. With a 5 GB image, you are mostly waiting on network and disk during this phase.

The catch: a large part of that data is often never read. An image with PyTorch, several models and half an operating system contains far more than a single invocation needs. This is where SOCI lazy loading helps.

How SOCI lazy loading works

SOCI stands for Seekable OCI. OCI is the open standard for container images. The project comes from AWS and is open source under Apache-2.0. SOCI does not change your image. Instead, it creates an additional index that records for each file in which layer and at which position it is stored. With this table of contents, Lambda can fetch individual files from ECR instead of downloading everything in one go.

On Lambda Managed Instances, the flow looks like this: you push the image and the SOCI index together to ECR under a separate tag. That tag points to an image index with two entries, the regular image manifest and the SOCI index. If your function points to this tag, Lambda detects the index when you publish the version and turns on lazy loading. There are no further settings.

🎬 Startup with and without SOCI – this animated diagram only runs on my site: watch it on sascha-ms.de

When the files are fetched

Files your init code reads are fetched by Lambda during initialization. Anything the handler touches only later gets pulled in during that invocation, which then takes correspondingly longer. According to the documentation, Lambda does not download the rest of the image in the background. That gives you the most important rule for your code: import every library and read every file you need in the init phase. Then your invocation durations stay consistent.

From a plain image to an image index with a SOCI index: five steps to the function.

Prerequisites for SOCI lazy loading

An AWS account in a Region where Lambda Managed Instances are available, and AWS CLI v2
Node.js 22 or later, Docker with buildx and AWS CDK v2 (here aws-cdk-lib 2.275.0)
For the SOCI step, a Linux machine with containerd, for example a small EC2 instance with Amazon Linux 2023 and a Graviton processor
A function packaged as a container image for one architecture, here arm64
The jq command line tool and basic knowledge of TypeScript and CDK

A quick glossary: ECR is the AWS container registry. nerdctl is a Docker-like command line tool for containerd, and the SOCI snapshotter is the containerd extension that can create and read SOCI indexes.

Setting up SOCI lazy loading step by step

Our example is a recommendation service for a library. For every book ID, it returns the five most similar books. It computes the similarity from vectors stored in one binary file per language. The image contains models for German, English, French and Spanish, but the function reads only one of them. I chose this on purpose, because exactly this pattern shows up in real images all the time.

Step 1: Create the project

mkdir lmi-soci-library && cd lmi-soci-library
mkdir -p src scripts lib bin test
npm init -y

Replace the generated package.json with this version. "type": "module" makes Node.js load the compiled files as ES modules, including inside the container.

{
  "name": "lmi-soci-library",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "build": "tsc -p tsconfig.build.json",
    "models": "node --experimental-strip-types scripts/make-models.ts",
    "test": "node --experimental-strip-types --test test/*.test.ts",
    "measure": "node --experimental-strip-types scripts/measure-start.ts"
  },
  "dependencies": {},
  "devDependencies": {
    "@aws-sdk/client-lambda": "3.1159.0",
    "@types/node": "^22.19.0",
    "aws-cdk": "2.1146.1",
    "aws-cdk-lib": "2.275.0",
    "constructs": "^10.4.2",
    "typescript": "7.0.2"
  }
}

You run the scripts under scripts/ and the tests directly from TypeScript, using the Node.js 22 option --experimental-strip-types. For the container, on the other hand, you compile to dist/. Two small configuration files handle this:

// tsconfig.json
{
  "compilerOptions": {
    "target": "es2023",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "strict": true,
    "allowImportingTsExtensions": true,
    "rewriteRelativeImportExtensions": true,
    "skipLibCheck": true,
    "types": ["node"],
    "outDir": "dist"
  },
  "include": ["src", "scripts", "lib", "bin", "test"]
}

// tsconfig.build.json
{
  "extends": "./tsconfig.json",
  "compilerOptions": { "rootDir": "src", "outDir": "dist" },
  "include": ["src"]
}

npm install

Step 2: Load and compare vectors

The module reads a file in the format “magic bytes, count, dimensions, values” and compares books using cosine similarity. Cosine similarity measures how closely two vectors point in the same direction: 1 means very similar, 0 means unrelated.

// src/vectors.ts
import { readFileSync } from 'node:fs';

export interface BookVectors {
  count: number;
  dims: number;
  data: Float32Array;
}

const MAGIC = 'BKV1';
const HEADER_BYTES = 12;

/** Writes vectors in a simple binary format: "BKV1", count, dims, float32 values. */
export function encodeVectors(v: BookVectors): Buffer {
  const header = Buffer.alloc(HEADER_BYTES);
  header.write(MAGIC, 0, 'ascii');
  header.writeUInt32LE(v.count, 4);
  header.writeUInt32LE(v.dims, 8);
  const body = Buffer.from(v.data.buffer, v.data.byteOffset, v.data.byteLength);
  return Buffer.concat([header, body]);
}

export function decodeVectors(buf: Buffer): BookVectors {
  if (buf.subarray(0, 4).toString('ascii') !== MAGIC) {
    throw new Error('Unknown file format: magic bytes missing');
  }
  const count = buf.readUInt32LE(4);
  const dims = buf.readUInt32LE(8);
  const expected = HEADER_BYTES + count * dims * 4;
  if (buf.byteLength !== expected) {
    throw new Error(`File size ${buf.byteLength} does not match ${expected} bytes`);
  }
  // Copy into an aligned buffer so Float32Array works on every offset
  const data = new Float32Array(count * dims);
  data.set(new Float32Array(buf.buffer.slice(buf.byteOffset + HEADER_BYTES, buf.byteOffset + expected)));
  return { count, dims, data };
}

export function loadVectors(path: string): BookVectors {
  return decodeVectors(readFileSync(path));
}

function cosine(v: BookVectors, a: number, b: number): number {
  let dot = 0;
  let na = 0;
  let nb = 0;
  const oa = a * v.dims;
  const ob = b * v.dims;
  for (let i = 0; i < v.dims; i++) {
    const x = v.data[oa + i];
    const y = v.data[ob + i];
    dot += x * y;
    na += x * x;
    nb += y * y;
  }
  return na === 0 || nb === 0 ? 0 : dot / Math.sqrt(na * nb);
}

export interface Recommendation {
  bookId: number;
  score: number;
}

/** Returns the books most similar to bookId (without bookId itself). */
export function similarBooks(v: BookVectors, bookId: number, limit = 5): Recommendation[] {
  if (!Number.isInteger(bookId) || bookId < 0 || bookId >= v.count) {
    throw new RangeError(`bookId must be between 0 and ${v.count - 1}`);
  }
  const best: Recommendation[] = [];
  for (let other = 0; other < v.count; other++) {
    if (other === bookId) continue;
    const score = cosine(v, bookId, other);
    if (best.length < limit || score > best[best.length - 1].score) {
      best.push({ bookId: other, score });
      best.sort((x, y) => y.score - x.score);
      if (best.length > limit) best.pop();
    }
  }
  return best.map((r) => ({ bookId: r.bookId, score: Math.round(r.score * 1000) / 1000 }));
}

Step 3: A handler that loads in the init phase

The handler loads the model at the top level, which means during initialization. With SOCI, this is the moment Lambda fetches the file from ECR. If the call to loadVectors lived inside the handler, the first invocation of every environment would take noticeably longer.

// src/handler.ts
import { loadVectors, similarBooks, type Recommendation } from './vectors.ts';

// Load in the init phase: with SOCI, Lambda fetches the file here
// and not during the first invocation.
const MODEL_FILE = process.env.MODEL_FILE ?? '/opt/models/books-de.bin';
const started = Date.now();
const vectors = loadVectors(MODEL_FILE);
console.log(JSON.stringify({ msg: 'model loaded', file: MODEL_FILE, books: vectors.count, ms: Date.now() - started }));

export interface RecommendEvent {
  bookId: number;
  limit?: number;
}

export interface RecommendResult {
  model: string;
  recommendations: Recommendation[];
}

// Read-only shared state: safe even when an execution environment
// handles several invocations at the same time.
export async function handler(event: RecommendEvent): Promise<RecommendResult> {
  const limit = Math.min(Math.max(event.limit ?? 5, 1), 20);
  return { model: MODEL_FILE, recommendations: similarBooks(vectors, event.bookId, limit) };
}

Step 4: Generate test data and check locally

The script creates four model files with random values. With BOOKS=200000, every file grows to roughly 100 MB, and the difference at startup becomes clearly visible. Small files are enough for the first test.

// scripts/make-models.ts
// Generates one vector file per language. Only one of them is used per function –
// exactly the situation in which SOCI lazy loading pays off.
import { mkdirSync, writeFileSync } from 'node:fs';
import { encodeVectors } from '../src/vectors.ts';

const count = Number(process.env.BOOKS ?? 20000);
const dims = Number(process.env.DIMS ?? 128);
const languages = (process.env.LANGS ?? 'de,en,fr,es').split(',');

mkdirSync('models', { recursive: true });
let seed = 42;
const random = () => {
  seed = (seed * 1664525 + 1013904223) % 2 ** 32;
  return seed / 2 ** 32 - 0.5;
};

for (const lang of languages) {
  const data = new Float32Array(count * dims);
  for (let i = 0; i < data.length; i++) data[i] = random();
  const file = `models/books-${lang}.bin`;
  const buf = encodeVectors({ count, dims, data });
  writeFileSync(file, buf);
  console.log(`${file}: ${(buf.byteLength / 1024 / 1024).toFixed(1)} MB`);
}

BOOKS=5000 npm run models
npm test
npm run build
MODEL_FILE=models/books-de.bin node -e "import('./dist/handler.js').then(async (m) => console.log(await m.handler({ bookId: 7, limit: 3 })))"

Expected result: four files of 2.4 MB each, four passing tests and an output with three recommendations. Book IDs and scores are random; the structure looks like this:

{"msg":"model loaded","file":"models/books-de.bin","books":5000,"ms":4}
{
  model: 'models/books-de.bin',
  recommendations: [
    { bookId: 37, score: 0.337 },
    { bookId: 1965, score: 0.311 },
    { bookId: 3426, score: 0.274 }
  ]
}

Step 5: Build the image for arm64 and push it to ECR

The Dockerfile uses the official Lambda base image for Node.js 24. The models end up in /opt/models.

# Dockerfile
FROM public.ecr.aws/lambda/nodejs:24

# Compiled code plus package.json (for "type": "module")
COPY package.json ${LAMBDA_TASK_ROOT}/
COPY dist/ ${LAMBDA_TASK_ROOT}/

# All language models – each function only reads one of them
COPY models/ /opt/models/

CMD ["handler.handler"]

Two build options matter here. --platform linux/arm64, because Lambda accepts only single-architecture images. And --provenance=false, because buildx would otherwise attach an attestation to the image and turn it into an image index with several entries. For the SOCI step, you want a plain image without such extras.

BOOKS=200000 npm run models && npm run build

ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
REGION=eu-central-1
REPO=library-recommender
REGISTRY=$ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com

aws ecr create-repository --repository-name $REPO --region $REGION
aws ecr get-login-password --region $REGION | docker login -u AWS --password-stdin $REGISTRY

docker buildx build --platform linux/arm64 --provenance=false --sbom=false \
  -t $REGISTRY/$REPO:v1 --push .

Step 6: Create the SOCI index

You run this step on a Linux machine with containerd. The easiest option is a small Graviton instance with Amazon Linux 2023, because its architecture already matches the image. The instance needs a role with read and write access to the ECR repository.

sudo yum install -y soci-snapshotter containerd nerdctl
sudo systemctl start soci-snapshotter
sudo systemctl restart containerd

ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
REGION=eu-central-1
REPO=library-recommender
REGISTRY=$ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com

aws ecr get-login-password --region $REGION | sudo nerdctl login -u AWS --password-stdin $REGISTRY

sudo nerdctl pull --platform linux/arm64 $REGISTRY/$REPO:v1
sudo nerdctl image convert --soci --platform linux/arm64 $REGISTRY/$REPO:v1 $REGISTRY/$REPO:v1-soci
sudo nerdctl push --platform linux/arm64 $REGISTRY/$REPO:v1-soci

nerdctl image convert --soci produces an index in format v2, and that is the only format Lambda accepts. When you follow older guides on the web, check which format they produce: Lambda does not support indexes in format v1.

Step 7: Check the result in ECR

Before you touch the function, take a look at the new tag. The manifest behind v1-soci must have exactly two entries, and one of them must be the SOCI index.

aws ecr batch-get-image --repository-name $REPO --region $REGION \
  --image-ids imageTag=v1-soci \
  --accepted-media-types application/vnd.oci.image.index.v1+json \
  --query 'images[0].imageManifest' --output text | jq '.manifests | length, [.[] | .artifactType // .mediaType]'

Expected result: the first line shows 2, and the list contains an entry with soci in its name. If you see a higher number, attestations or additional platforms are still attached to the image. In that case, rebuild the image as in step 5.

Step 8: Capacity provider and function with CDK

Since version 2.235.0, aws-cdk-lib has a dedicated CapacityProvider construct. If you do not pass your own, it also creates the operator role with the managed policy AWSLambdaManagedEC2ResourceOperator. You attach a function to the provider with addFunction. The function is then published automatically as $LATEST.PUBLISHED, so you do not have to create a version by hand.

// lib/library-stack.ts
import { CfnOutput, Duration, Stack, type StackProps } from 'aws-cdk-lib';
import * as ec2 from 'aws-cdk-lib/aws-ec2';
import * as ecr from 'aws-cdk-lib/aws-ecr';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import type { Construct } from 'constructs';

export interface LibraryStackProps extends StackProps {
  repositoryName: string;
  /** Tag of the SOCI-indexed image, e.g. "v1-soci" */
  imageTag: string;
  /** Optional: original tag (e.g. "v1") for a comparison function without SOCI */
  plainImageTag?: string;
}

export class LibraryStack extends Stack {
  constructor(scope: Construct, id: string, props: LibraryStackProps) {
    super(scope, id, props);

    // Private subnets with a NAT gateway so the instances can reach ECR and CloudWatch
    const vpc = new ec2.Vpc(this, 'LibraryVpc', { maxAzs: 3, natGateways: 1 });
    const sg = new ec2.SecurityGroup(this, 'InstancesSg', { vpc, allowAllOutbound: true });

    const capacity = new lambda.CapacityProvider(this, 'LibraryCapacity', {
      subnets: vpc.privateSubnets,
      securityGroups: [sg],
      architectures: [lambda.Architecture.ARM_64],
      maxVCpuCount: 12,
    });

    const repo = ecr.Repository.fromRepositoryName(this, 'Repo', props.repositoryName);

    const addRecommender = (id: string, tag: string) => {
      const fn = new lambda.DockerImageFunction(this, id, {
        code: lambda.DockerImageCode.fromEcr(repo, { tagOrDigest: tag }),
        architecture: lambda.Architecture.ARM_64,
        memorySize: 4096,
        timeout: Duration.seconds(30),
        environment: { MODEL_FILE: '/opt/models/books-de.bin' },
      });
      capacity.addFunction(fn, {
        perExecutionEnvironmentMaxConcurrency: 8,
        latestPublishedScalingConfig: { minExecutionEnvironments: 3, maxExecutionEnvironments: 6 },
      });
      new CfnOutput(this, `${id}Name`, { value: fn.functionName });
      return fn;
    };

    addRecommender('Recommender', props.imageTag);
    if (props.plainImageTag) {
      addRecommender('RecommenderPlain', props.plainImageTag);
    }
  }
}

// bin/app.ts
import { App } from 'aws-cdk-lib';
import { LibraryStack } from '../lib/library-stack.ts';

const app = new App();
new LibraryStack(app, 'LibraryRecommender', {
  repositoryName: app.node.tryGetContext('repo') ?? 'library-recommender',
  imageTag: app.node.tryGetContext('tag') ?? 'v1-soci',
  plainImageTag: app.node.tryGetContext('plainTag'),
  env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEFAULT_REGION },
});

// cdk.json
{
  "app": "node --experimental-strip-types bin/app.ts"
}

A few values in the stack are deliberate: according to CDK, maxVCpuCount must be between 12 and 15,000. perExecutionEnvironmentMaxConcurrency: 8 allows eight concurrent invocations per environment, which is rather generous for our compute-heavy handler. For pure CPU work, more concurrency per vCPU does not help much; more memory, and with it more vCPUs per function, helps more.

npx cdk bootstrap
npx cdk deploy -c repo=library-recommender -c tag=v1-soci -c plainTag=v1

With -c plainTag=v1, the stack creates a second function that points to the image without a SOCI index. You need it for the comparison in the next step. The deployment takes a few minutes, because Lambda launches the instances.

Step 9: Measure startup time with and without SOCI

The script publishes a new version for each function and measures the time until it is Active. It is a rough but honest measurement: it includes pulling the image and initializing the environments.

// scripts/measure-start.ts
// Publishes a new version per function and measures the time until it is "Active".
// Usage: npm run measure -- recommender-plain recommender-soci
import {
  GetFunctionConfigurationCommand,
  LambdaClient,
  PublishVersionCommand,
} from '@aws-sdk/client-lambda';
import { setTimeout as sleep } from 'node:timers/promises';

const client = new LambdaClient({});

async function timeToActive(functionName: string): Promise<number> {
  const start = Date.now();
  const { Version } = await client.send(new PublishVersionCommand({ FunctionName: functionName }));
  for (;;) {
    const cfg = await client.send(
      new GetFunctionConfigurationCommand({ FunctionName: functionName, Qualifier: Version }),
    );
    if (cfg.State === 'Active') return (Date.now() - start) / 1000;
    if (cfg.State === 'Failed') throw new Error(`${functionName}:${Version} failed: ${cfg.StateReason}`);
    await sleep(5000);
  }
}

const names = process.argv.slice(2);
if (names.length === 0) {
  console.error('Please pass at least one function name');
  process.exit(1);
}
for (const name of names) {
  const seconds = await timeToActive(name);
  console.log(`${name}: active after ${seconds.toFixed(0)} s`);
}

npm run measure -- <name of the plain function> <name of the SOCI function>

You will find the function names in the outputs of cdk deploy. Measure several times and compare the averages, because network and placement vary. It is also worth checking CloudWatch Logs for the model loaded line and the duration of each first invocation. If you measure numbers with your own image, I would love to read about them in the comments.

Common mistakes with SOCI lazy loading

The function points to the old tag. The image URI must point to v1-soci, not to v1. Otherwise everything works, just without lazy loading.
Index in the wrong format. Lambda supports only SOCI Index Manifest v2. Check for the media type application/vnd.amazon.soci.index.v2+json.
Too many entries in the image index. Attestations, SBOMs or a multi-arch image lead to more than two entries in the index.
Files read only in the handler. Then the first invocation of every environment pays the loading time, and your latency metrics get outliers.
Mismatched architecture. Capacity provider, function and image must share the same architecture, here arm64 everywhere.
New image, old index. Every change to the image needs a new SOCI tag, for example v2-soci, and an updated image URI.

Costs and security

The announcement does not mention a separate price for SOCI itself. The index is stored as an additional artifact in ECR and is small compared to the image. The real costs come from Lambda Managed Instances: you pay the EC2 price of the instances plus a 15 percent management fee. Savings Plans and Reserved Instances apply only to the EC2 part. In this example, you also pay for a NAT gateway and the EC2 instance used for the SOCI step. Clean up after testing:

npx cdk destroy
aws ecr delete-repository --repository-name library-recommender --region eu-central-1 --force

On the security side, the capacity provider is the security boundary. Functions that share a provider run as containers on the same instances. Separate functions with different protection needs by giving them their own capacity providers. The operator role needs only the managed policy, and the role of the build instance needs access to just the one repository.

My take

SOCI lazy loading solves a real problem, but a narrow one. It helps only container image functions on Lambda Managed Instances, not the classic Lambda most of us use every day. If you run large images there, an extra build step gets you faster starts when publishing and when scaling out. That is mainly interesting for ML workloads, where an image ships many models or libraries.

Where I am cautious: the build process gets more complicated. You need containerd and nerdctl, a Linux machine with the matching architecture and a second tagging scheme. That belongs in the CI pipeline, not on someone’s laptop. And lazy loading is no substitute for lean images. If your function ends up reading almost everything anyway, you gain little. My advice: clean up the image first, then measure, then add SOCI. By the way, for Java functions on regular Lambda, SnapStart remains the tool of choice for startup times.

FAQ

Does SOCI lazy loading work with regular Lambda?

No. As of late October 2026, Lambda supports SOCI only for functions that are packaged as container images and run on Lambda Managed Instances.

Do I have to change my function code for SOCI?

Not necessarily. You should, however, load all libraries and files in the init phase, so the first invocation of an environment is not slowed down by on-demand fetching.

Can I create the SOCI index with Docker?

The AWS documentation shows the path with containerd, nerdctl and the SOCI snapshotter. Docker alone does not create a SOCI index, so you need an environment with containerd for this step.

How much faster does my function start with SOCI?

AWS quotes startup times that are up to 70 percent shorter. How much you gain depends on which share of the image is actually read. Measure it with and without the index.

Your next step

Take your largest container image and find out which share of it is really read at startup. If it is less than half, and you are considering Lambda Managed Instances anyway, SOCI is a good candidate for an experiment. What makes your Lambda images so large: models, libraries or something else entirely?

Sources

This post was created with AI assistance.

👉 Next step: Curious what your own Lambda functions cost? Try my Lambda cost calculator – it runs right in your browser.

Originally published on sascha-ms.de. More articles on serverless, AI in everyday development and leading tech teams: sascha-ms.de/en

Monitoring durable functions: telemetry in TypeScript

Sascha Mirow-Stanitzok — Sun, 01 Nov 2026 09:55:06 +0000

Monitoring durable functions used to feel like a puzzle. A workflow that waits two days for a book to be shipped is spread across several Lambda invocations, and every invocation writes its own log lines. Answering “Which executions got stuck in the order-copy step yesterday?” took real effort.

Since October 28, 2026, there is the Durable Execution Telemetry Exporter for exactly this. It turns every execution into a single record and sends it to a destination of your choice, for example CloudWatch Logs or DynamoDB. I took a closer look because it fills the gap that bothered me most after writing my article about Lambda durable functions. In this article you build a small interlibrary loan workflow for a city library step by step, redact personal data, deploy everything with the AWS CDK and finally query the data in plain English through an MCP server.

In short

The telemetry exporter hooks into the Durable Execution SDK as a plugin. For each execution it builds a complete JSON record with status, steps, duration and errors and sends it to up to 13 destinations. The plugin itself costs nothing extra; you only pay for the destination. The biggest pitfall: executions that Lambda stops or times out on its own do not show up unless you add them via EventBridge.

What you will learn in this article

How the telemetry exporter builds records and when it sends them
Redacting input and output before they leave the function
Testing the exporter locally, without an AWS account, using your own in-memory exporter
Backfilling STOPPED and TIMED_OUT with an EventBridge rule
Querying telemetry with Claude Code and the MCP server

Why monitoring durable functions is harder

A durable function is a Lambda function that saves its progress in checkpoints. A checkpoint is a stored intermediate result: once a step has finished, Lambda does not run it again on the next invocation but reads the result from storage instead. When the workflow waits, Lambda ends the invocation and starts a new one later. This resuming is called replay.

For business logic that is great. For monitoring, however, it means that one business execution consists of many technical invocations. Classic Lambda metrics such as duration or error rate describe the single invocation, not the workflow. In addition, Lambda keeps the execution history only for the configured retention period, at most 90 days. So if you want to ask later how long loans take on average, you need the data in a place of your own.

That is exactly what the exporter takes care of. It is therefore worth looking at how it works before we write code.

What the telemetry exporter does

The exporter is a plugin that runs in the same process as your handler. It hooks into the SDK lifecycle but does not sit in the request path. On every invocation it builds a cumulative snapshot of the entire execution from the checkpoints, so it is not a delta. A later record therefore always replaces an earlier one.

AWS offers the plugin for TypeScript, Python, Java and Go. According to the announcement, it comes at no additional charge and is available in all Regions that support durable functions. Costs only arise at the destination, such as log ingestion or DynamoDB writes.

One record instead of a hundred log lines

Here is a record from our example (shortened). All fields come from the package’s DurableExecutionTelemetryRecord type:

{
  "recordType": "DurableExecutionTelemetry",
  "schemaVersion": "1.0",
  "executionArn": "arn:aws:lambda:eu-central-1:111122223333:function:LoanWorkflow:live/durable-execution/…",
  "functionName": "LoanWorkflow",
  "functionQualifier": "live",
  "status": "SUCCEEDED",
  "startTime": "2026-10-29T08:00:00.000Z",
  "endTime": "2026-10-31T08:00:02.410Z",
  "input": { "requestId": "FL-1001", "isbn": "9783161484100" },
  "output": { "status": "READY_FOR_PICKUP", "partnerLibrary": "North City Library" },
  "operations": [
    { "name": "find-partner-library", "type": "STEP", "status": "SUCCEEDED", "durationMs": 41, "result": "North City Library" },
    { "name": "order-copy", "type": "STEP", "status": "SUCCEEDED", "durationMs": 63 },
    { "name": "shipping", "type": "WAIT", "status": "SUCCEEDED" },
    { "name": "notify-reader", "type": "STEP", "status": "SUCCEEDED", "durationMs": 88 }
  ]
}

The operations field is the interesting part. Every step and every wait appears there with status and duration. Results of individual steps are left out by default unless you explicitly allow them. That is a good default, because step results often contain exactly the data that does not belong in monitoring.

When a record is created

With emitMode you decide how often the exporter sends. Your choice directly affects cost and freshness:

emitMode	When it sends	Good for
`on-complete` (default)	once on SUCCEEDED or FAILED	analysis, dashboards
`on-failure`	only on FAILED	error analysis, lowest overhead
`on-change`	on every status change, including RUNNING	live progress, highest load

On top of that there is samplingRate between 0 and 1. The decision is based on a hash of the execution ARN. An execution is therefore either recorded completely or not at all, never halfway. Each of the 13 destinations has its own class, from LambdaLogExporter (the function’s own log, no extra IAM permissions) through S3Exporter for Athena to OTelExporter for any OpenTelemetry backend. You can combine several destinations, and the exporter serves them in parallel.

The path of a telemetry record: from the plugin inside the function to querying it via MCP.

Step by step: monitoring durable functions for an interlibrary loan

Our example: a reader orders a book that her own library does not have. The workflow looks for a partner library, orders a copy there, waits for shipping and notifies the reader. The workflow needs her name and email address, but they have no business in monitoring.

Prerequisites

Node.js 22 or later (the exporter requires at least 22)
AWS CLI v2 with credentials for a test account
A basic understanding of durable functions, for example from my introductory article
About 30 minutes

Step 1: Create the project

Create the project and install the SDK, the exporter and the CDK. You only need the testing package locally:

mkdir library-loan && cd library-loan
npm init -y
npm pkg set type=module
npm install @aws/durable-execution-sdk-js @aws/durable-execution-sdk-js-telemetry-exporter \
  @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb aws-cdk-lib constructs
npm install -D typescript @types/node @types/aws-lambda tsx esbuild aws-cdk \
  @aws/durable-execution-sdk-js-testing
mkdir src lib bin test

For tests to run outside Lambda, you also need the optional peer dependencies. At startup the exporter loads every AWS client, including the ones you do not use. In Lambda the Node.js runtime provides them; locally it does not:

npm install -D @aws-sdk/client-s3 @aws-sdk/util-dynamodb @aws-sdk/client-rds-data \
  @aws-sdk/client-cloudwatch-logs @aws-sdk/client-firehose @aws-sdk/client-eventbridge \
  @aws-sdk/client-redshift-data @aws-sdk/client-sqs @aws-sdk/credential-provider-node \
  "@smithy/signature-v4@^4" @aws-crypto/sha256-js

The tsconfig.json is deliberately strict. The cdk.json starts the app with tsx:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "noEmit": true,
    "types": ["node"]
  },
  "include": ["src", "lib", "bin", "test"]
}

{
  "app": "npx tsx bin/app.ts"
}

Step 2: Configure telemetry and redact data

The configuration lives in its own file. Two small functions decide what is left of input and output. I also allow the result of a single step, because it only contains the partner library’s name and helps with troubleshooting:

// src/telemetry.ts
import {
  DynamoDBExporter,
  LambdaLogExporter,
  durableExecutionTelemetry,
  type TelemetryExporter,
} from "@aws/durable-execution-sdk-js-telemetry-exporter";

export interface LoanRequest {
  requestId: string;
  isbn: string;
  readerName: string;
  readerEmail: string;
}

export interface LoanResult {
  status: "READY_FOR_PICKUP" | "NOT_AVAILABLE";
  pickupCode?: string;
  partnerLibrary?: string;
}

// Only fields needed for troubleshooting – no personal data.
export function redactInput(input: unknown): { requestId?: string; isbn?: string } {
  const req = (input ?? {}) as Partial<LoanRequest>;
  return { requestId: req.requestId, isbn: req.isbn };
}

// Nobody needs the pickup code in monitoring.
export function redactOutput(output: unknown): { status?: string; partnerLibrary?: string } {
  const res = (output ?? {}) as Partial<LoanResult>;
  return { status: res.status, partnerLibrary: res.partnerLibrary };
}

export function parseSamplingRate(raw: string | undefined): number {
  const value = Number(raw ?? "1");
  if (Number.isNaN(value)) return 1;
  return Math.min(1, Math.max(0, value));
}

export function defaultExporters(): TelemetryExporter[] {
  const exporters: TelemetryExporter[] = [new LambdaLogExporter()];
  const tableName = process.env.TELEMETRY_TABLE;
  if (tableName) {
    exporters.push(new DynamoDBExporter({ tableName }));
  }
  return exporters;
}

export function createTelemetry(exporters: TelemetryExporter[]) {
  return durableExecutionTelemetry({
    emitMode: "on-complete",
    samplingRate: parseSamplingRate(process.env.TELEMETRY_SAMPLING_RATE),
    exporters,
    content: {
      input: redactInput,
      output: redactOutput,
      operations: {
        includeErrors: true,
        overrides: [
          // Deliberately export this step's result (it only contains the library name)
          { operationName: "find-partner-library", result: (r) => r },
        ],
      },
    },
  });
}

Two details matter. First, you create the plugin once at module scope, not inside the handler. Second, the sampling rate does not throw on nonsense like “7” but gets clamped by my helper. The exporter itself would also correct invalid values and log a warning.

Step 3: Write the workflow

The workflow consists of three steps and one wait. The business logic is intentionally just a placeholder. To make it testable, the file also exports a factory function that accepts any exporters:

// src/loan-workflow.ts
import {
  type DurableContext,
  withDurableExecution,
} from "@aws/durable-execution-sdk-js";
import type { TelemetryExporter } from "@aws/durable-execution-sdk-js-telemetry-exporter";
import {
  createTelemetry,
  defaultExporters,
  type LoanRequest,
  type LoanResult,
} from "./telemetry.js";

// Placeholders for real business logic (catalog, partner library, email)
async function findPartnerLibrary(isbn: string): Promise<string | null> {
  return isbn.startsWith("978") ? "North City Library" : null;
}

async function orderCopy(library: string, requestId: string): Promise<string> {
  return `${library.slice(0, 3).toUpperCase()}-${requestId}`;
}

async function notifyReader(email: string, pickupCode: string): Promise<void> {
  // This is where the email with the pickup code would be sent – the log only shows the masked address.
  console.log(JSON.stringify({ msg: "reader notified", to: email.replace(/.+@/, "***@"), codeLength: pickupCode.length }));
}

async function loanWorkflow(
  event: LoanRequest,
  context: DurableContext,
): Promise<LoanResult> {
  const library = await context.step("find-partner-library", async () =>
    findPartnerLibrary(event.isbn),
  );

  if (!library) {
    return { status: "NOT_AVAILABLE" };
  }

  const pickupCode = await context.step("order-copy", async () =>
    orderCopy(library, event.requestId),
  );

  // Shipping between libraries: the function sleeps without using compute time.
  await context.wait("shipping", { seconds: Number(process.env.SHIPPING_SECONDS ?? "172800") });

  await context.step("notify-reader", async () =>
    notifyReader(event.readerEmail, pickupCode),
  );

  return { status: "READY_FOR_PICKUP", pickupCode, partnerLibrary: library };
}

// Factory so tests can plug in their own exporters
export function createHandler(exporters: TelemetryExporter[]) {
  return withDurableExecution(loanWorkflow, {
    plugins: [createTelemetry(exporters)],
  });
}

export const handler = createHandler(defaultExporters());

Pay attention to the operation names. They end up unchanged as keys in the records. In CloudWatch Logs Insights and OpenSearch a dot in a name works as a path separator, which is why I only use lowercase letters and hyphens.

Step 4: Test locally, without an AWS account

The testing package simulates the checkpoint backend in-process. Instead of a real destination, I plug in an exporter that just collects records in an array. The TelemetryExporter interface needs exactly one method for that:

// test/telemetry.test.ts
import { after, before, test } from "node:test";
import assert from "node:assert/strict";
import { LocalDurableTestRunner } from "@aws/durable-execution-sdk-js-testing";
import type {
  DurableExecutionTelemetryRecord,
  TelemetryExporter,
} from "@aws/durable-execution-sdk-js-telemetry-exporter";
import { parseSamplingRate } from "../src/telemetry.js";

process.env.SHIPPING_SECONDS = "1";
const { createHandler } = await import("../src/loan-workflow.js");

// Collects all records in memory instead of sending them
class MemoryExporter implements TelemetryExporter {
  records: DurableExecutionTelemetryRecord[] = [];
  async export(record: DurableExecutionTelemetryRecord): Promise<void> {
    this.records.push(record);
  }
}

before(() => LocalDurableTestRunner.setupTestEnvironment({ skipTime: false }));
after(() => LocalDurableTestRunner.teardownTestEnvironment());

test("exports one redacted record per completed execution", async () => {
  const memory = new MemoryExporter();
  const runner = new LocalDurableTestRunner({ handlerFunction: createHandler([memory]) });

  const execution = await runner.run({
    payload: {
      requestId: "FL-1001",
      isbn: "9783161484100",
      readerName: "Jane Doe",
      readerEmail: "jane@example.org",
    },
  });

  assert.equal(execution.getStatus(), "SUCCEEDED");
  assert.equal(memory.records.length, 1);

  const record = memory.records[0];
  assert.equal(record.status, "SUCCEEDED");
  assert.deepEqual(record.input, { requestId: "FL-1001", isbn: "9783161484100" });
  assert.deepEqual(record.output, { status: "READY_FOR_PICKUP", partnerLibrary: "North City Library" });

  const json = JSON.stringify(record);
  assert.ok(!json.includes("jane@example.org"), "email must not be exported");
  assert.ok(!json.includes("NOR-FL-1001"), "pickup code must not be exported");

  const names = record.operations.map((op) => op.name);
  assert.deepEqual(names, ["find-partner-library", "order-copy", "shipping", "notify-reader"]);
  const partner = record.operations.find((op) => op.name === "find-partner-library");
  assert.equal(partner?.result, "North City Library");
});

test("parseSamplingRate clamps invalid values", () => {
  assert.equal(parseSamplingRate(undefined), 1);
  assert.equal(parseSamplingRate("0.1"), 0.1);
  assert.equal(parseSamplingRate("7"), 1);
  assert.equal(parseSamplingRate("abc"), 1);
});

Add the script "test": "tsx --test test/*.test.ts" to your package.json and run the tests. The wait is set to one second in the test:

npx tsc --noEmit
npm test

Expected result:

{"msg":"reader notified","to":"***@example.org","codeLength":11}
✔ exports one redacted record per completed execution
✔ parseSamplingRate clamps invalid values
ℹ tests 2
ℹ pass 2
ℹ fail 0

The first test is the real win. It makes sure that neither the email address nor the pickup code ever lands in monitoring. If someone changes the redaction later, the test fails before any data reaches the cloud.

Step 5: Deploy with the AWS CDK

The stack contains the telemetry table, the workflow with durableConfig, an alias and the function that will close the gap later. For functions with durableConfig, the CDK automatically attaches the managed policy AWSLambdaBasicDurableExecutionRolePolicy; you grant write access to the table yourself:

// lib/loan-stack.ts
import * as path from "node:path";
import { fileURLToPath } from "node:url";
import { CfnOutput, Duration, RemovalPolicy, Stack, type StackProps } from "aws-cdk-lib";
import * as dynamodb from "aws-cdk-lib/aws-dynamodb";
import * as events from "aws-cdk-lib/aws-events";
import * as targets from "aws-cdk-lib/aws-events-targets";
import * as lambda from "aws-cdk-lib/aws-lambda";
import { NodejsFunction } from "aws-cdk-lib/aws-lambda-nodejs";
import * as logs from "aws-cdk-lib/aws-logs";
import type { Construct } from "constructs";

const here = path.dirname(fileURLToPath(import.meta.url));

export class LoanStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    // Target for the DynamoDBExporter: pk = execution ARN, sk = timestamp
    const telemetryTable = new dynamodb.TableV2(this, "TelemetryTable", {
      partitionKey: { name: "pk", type: dynamodb.AttributeType.STRING },
      sortKey: { name: "sk", type: dynamodb.AttributeType.STRING },
      billing: dynamodb.Billing.onDemand(),
      removalPolicy: RemovalPolicy.DESTROY, // demo only
    });

    const workflow = new NodejsFunction(this, "LoanWorkflow", {
      entry: path.join(here, "../src/loan-workflow.ts"),
      handler: "handler",
      runtime: lambda.Runtime.NODEJS_22_X,
      architecture: lambda.Architecture.ARM_64,
      timeout: Duration.minutes(1),
      memorySize: 512,
      durableConfig: {
        executionTimeout: Duration.days(7),
        retentionPeriod: Duration.days(14),
      },
      environment: {
        TELEMETRY_TABLE: telemetryTable.tableName,
        TELEMETRY_SAMPLING_RATE: "1",
        SHIPPING_SECONDS: "60",
      },
      logGroup: new logs.LogGroup(this, "LoanWorkflowLogs", {
        retention: logs.RetentionDays.ONE_MONTH,
        removalPolicy: RemovalPolicy.DESTROY,
      }),
    });
    telemetryTable.grantWriteData(workflow);

    // Durable functions need a qualified ARN (version or alias)
    const live = new lambda.Alias(this, "LiveAlias", {
      aliasName: "live",
      version: workflow.currentVersion,
    });

    // Close the gap: only Lambda itself reports STOPPED and TIMED_OUT
    const closeGaps = new NodejsFunction(this, "CloseGaps", {
      entry: path.join(here, "../src/close-gaps.ts"),
      handler: "handler",
      runtime: lambda.Runtime.NODEJS_22_X,
      architecture: lambda.Architecture.ARM_64,
      environment: { TELEMETRY_TABLE: telemetryTable.tableName },
    });
    telemetryTable.grantWriteData(closeGaps);

    new events.Rule(this, "StoppedOrTimedOut", {
      eventPattern: {
        source: ["aws.lambda"],
        detailType: ["Durable Execution Status Change"],
        detail: { status: ["STOPPED", "TIMED_OUT"] },
      },
      targets: [new targets.LambdaFunction(closeGaps)],
    });

    new CfnOutput(this, "WorkflowAliasArn", { value: live.functionArn });
    new CfnOutput(this, "TelemetryTableName", { value: telemetryTable.tableName });
  }
}

// bin/app.ts
import { App } from "aws-cdk-lib";
import { LoanStack } from "../lib/loan-stack.js";

const app = new App();
new LoanStack(app, "LibraryLoanStack");

When bundling, esbuild leaves out the @aws-sdk/* packages because the runtime ships them. Check, bootstrap and deploy:

npx tsc --noEmit
npx cdk bootstrap   # only once per account and region
npx cdk deploy

After the deployment the console shows two outputs: WorkflowAliasArn and TelemetryTableName. You will need both in a moment.

Step 6: Run it and look at the records

You always invoke durable functions through a qualified ARN, meaning a version or an alias. For long workflows, use the asynchronous invocation:

aws lambda invoke \
  --function-name "<WorkflowAliasArn from the output>" \
  --invocation-type Event \
  --cli-binary-format raw-in-base64-out \
  --payload '{"requestId":"FL-1001","isbn":"9783161484100","readerName":"Jane Doe","readerEmail":"jane@example.org"}' \
  response.json

In the stack the shipping time is set to 60 seconds. After a little over a minute the record shows up in the function’s log. In CloudWatch Logs Insights this query finds all telemetry records:

fields executionName, status, durationMs, input.requestId
| filter recordType = "DurableExecutionTelemetry"
| sort @timestamp desc
| limit 20

At the same time, the same record sits in DynamoDB, with the execution ARN as pk and the emit time as sk:

aws dynamodb scan \
  --table-name "<TelemetryTableName from the output>" \
  --projection-expression "pk, sk, #s" \
  --expression-attribute-names '{"#s":"status"}' \
  --max-items 5

🎬 Interlibrary loan flow with telemetry – this animated diagram only runs on my site: watch it on sascha-ms.de

Closing the gap for STOPPED and TIMED_OUT

One point is somewhat hidden in the AWS blog post: the plugin only sends when the function is invoked. If you stop an execution through the API or the execution timeout expires, Lambda sets the final status itself without calling your code. Telemetry then keeps the last state, which with on-complete means nothing at all.

Lambda reports every status change as an event on the EventBridge default bus, with the source aws.lambda. The EventBridge rule in the stack filters for the two critical statuses and calls a small function that writes a substitute record into the same table:

// src/close-gaps.ts
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";
import type { EventBridgeEvent } from "aws-lambda";

interface StatusChangeDetail {
  durableExecutionArn: string;
  durableExecutionName?: string;
  functionArn: string;
  status: string;
  startTimestamp: string;
  endTimestamp?: string;
}

const db = DynamoDBDocumentClient.from(new DynamoDBClient({}));

// Writes STOPPED and TIMED_OUT into the same table as the exporter.
export const handler = async (
  event: EventBridgeEvent<string, StatusChangeDetail>,
): Promise<void> => {
  const d = event.detail;
  await db.send(
    new PutCommand({
      TableName: process.env.TELEMETRY_TABLE,
      Item: {
        pk: d.durableExecutionArn,
        sk: d.endTimestamp ?? event.time,
        recordType: "DurableExecutionTelemetry",
        source: "eventbridge-gap-filler",
        executionArn: d.durableExecutionArn,
        executionName: d.durableExecutionName,
        functionArn: d.functionArn,
        status: d.status,
        startTime: d.startTimestamp,
        endTime: d.endTimestamp,
      },
    }),
  );
};

A detail you notice while reading: the Lambda documentation calls the event type Durable Execution Status Change, while the announcement blog post uses a different spelling. I went with the Lambda documentation. After deploying, trigger a timeout once and check that the rule fires. Also check that the ARN in the event matches the telemetry’s executionArn, so both entries end up under the same pk.

Monitoring durable functions with AI: the MCP server

Together with the exporter, AWS released an MCP server. MCP (Model Context Protocol) is an open standard that lets AI assistants call tools. The server runs locally via npx, reads its configuration only from environment variables and uses the regular AWS credential chain. This is how you add it to Claude Code:

claude mcp add durable-telemetry \
  --scope project \
  --env DURABLE_TELEMETRY_DESTINATION_TYPE=dynamodb \
  --env DURABLE_TELEMETRY_DYNAMODB_TABLE_NAME=<TelemetryTableName> \
  --env DURABLE_TELEMETRY_REGION=eu-central-1 \
  -- npx -y @aws/durable-execution-sdk-js-telemetry-mcp

After that, five tools are available: test_destination checks the connection, describe_schema returns the schema, list_executions and get_execution filter without a query language, and query handles everything else. The assistant can then answer questions like “Which loans failed this week, and in which step?” straight from the table.

The server takes security seriously. SQL destinations accept only SELECT queries, and before the first query it asks for confirmation, because it cannot prove that your credentials are read-only. You should make that true by giving the server its own role with read permissions only. For DynamoDB, this policy is enough:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dynamodb:DescribeTable",
        "dynamodb:GetItem",
        "dynamodb:BatchGetItem",
        "dynamodb:Query",
        "dynamodb:Scan",
        "dynamodb:PartiQLSelect"
      ],
      "Resource": "arn:aws:dynamodb:eu-central-1:111122223333:table/<TelemetryTableName>"
    }
  ]
}

If you want to build an MCP server yourself, you will find the basics in my guide to MCP servers with TypeScript.

Costs and data protection

The plugin is free; the destinations are not. With on-complete you write one record per execution, with on-change considerably more. As a rough estimate, multiply the number of executions by the number of status changes. With many executions, a lower sampling rate and on-failure for less important workflows help.

On data protection my recommendation is clear: redact too much rather than too little. By default the exporter sends input and output in full. That is convenient, but the wrong starting point for workflows with customer data. Keep in mind, too, that your telemetry destination now holds a copy of the data. The DynamoDB table therefore needs a retention rule, for example a cleanup job or a custom exporter that sets a TTL attribute. I show how to add alarms and budgets in Lambda in Monitoring Lambda with CDK.

Common mistakes

ERR_MODULE_NOT_FOUND for @aws-sdk/client-s3: The peer dependencies are missing locally. Install the complete list from step 1, even if you do not use S3.
No records for stopped executions: That is by design. No invocation, no plugin, hence the EventBridge rule.
Step results are missing: Results are excluded by default. Allow them per operation via content.operations.overrides.
Encrypted results in the record: Transforms receive the stored, serialized result. If a step uses custom Serdes, you will not see plain text there.
Incomplete tree for map and parallel: After a resume, full-tree only shows child operations with pluginsConfig.childOperationsDepth, which costs extra replays.
Slow invocations under load: Exports run one after another. A slow exporter delays every execution that ends at the same time, not just one.

My take

I consider the exporter the most important addition since durable functions were released. Until now, the candid answer to “How do I monitor this?” was something like “with patience”. Now there is a well-designed data model, sensible defaults and a clean interface for plugging in your own destinations. I particularly like that sampling decides per execution and never records half a workflow.

I see two things critically. The STOPPED and TIMED_OUT gap is documented but easy to miss, and those are exactly the cases you want to see in operations. Second, the default configuration sends all input and output. For an example that is handy; for production I would wish for the opposite. The MCP server, on the other hand, strikes me as a good example of AI helping in operations without doing harm: read-only, with a confirmation prompt and clear limits.

Do you still need Step Functions for visibility? For workflows that business teams should follow graphically, the Step Functions console keeps its edge. For teams that prefer writing their flows in TypeScript, visibility is no longer an argument against durable functions.

FAQ

Does the telemetry exporter for durable functions cost extra?

No. According to AWS, the plugin is available at no additional charge. You only pay for the destination, such as CloudWatch Logs ingestion, DynamoDB writes or S3 storage.

Which destinations does the exporter support?

There are 13 built-in destinations, including CloudWatch Logs, S3, DynamoDB, Aurora, Redshift, OpenSearch, EventBridge, Firehose, SQS, OpenTelemetry, HTTPS endpoints and files. You build your own destinations with the TelemetryExporter interface.

Do I need additional IAM permissions?

Not for the default LambdaLogExporter, because the function is already allowed to write its own log. For every other destination, the function needs write permissions on that destination.

Does the exporter work with Python too?

Yes. The plugin exists for TypeScript, Python, Java and Go, each in the repository of the matching Durable Execution SDK.

Your next step

Take an existing durable function, attach the plugin with the LambdaLogExporter and write the test from step 4 for your redaction first. It takes half an hour, and afterwards you will see your workflows as a whole for the first time. I am curious: which question would you ask your telemetry first?

Sources

This post was created with AI assistance.

👉 Next step: Curious what your own Lambda functions cost? Try my Lambda cost calculator – it runs right in your browser.

Originally published on sascha-ms.de. More articles on serverless, AI in everyday development and leading tech teams: sascha-ms.de/en

AgentCore CLI 1.0: Deploy an AI Agent with TypeScript

Sascha Mirow-Stanitzok — Sun, 01 Nov 2026 08:55:03 +0000

With the AgentCore CLI 1.0, generally available since October 28, 2026, AWS ships the tool you use to create AI agents on Amazon Bedrock AgentCore, test them locally and deploy them. Many agent experiments never make it off the laptop. That is rarely the model’s fault. Usually the boring part in between is missing: how does the code get into a runtime environment, who is allowed to call it, and where do the logs end up?

That is exactly the part the CLI wants to take off your hands. So I installed version 1.0 and built a small agent for a made-up bookstore with it. In this article I walk you through the whole path in TypeScript: from an empty folder via a local test to a call in AWS – and where you need to be careful with existing projects.

In short

The AgentCore CLI 1.0 scaffolds a project, runs the agent locally and deploys it via CDK to the AgentCore Runtime. For a TypeScript agent with your own tools you need about five commands and two files. The biggest stumbling block: projects from version 0.x have to be moved over with agentcore migrate, and parts of the online docs still describe the old commands.

What you will learn in this article

What runtime, harness and memory mean in AgentCore
How to create a TypeScript agent with your own tools and test it locally
How to ship the agent to AWS with agentcore deploy and call it
How to move a 0.x project safely with agentcore migrate
What it costs and how to tear everything down again

What is the AgentCore CLI?

Amazon Bedrock AgentCore is the AWS platform meant to run AI agents in production. It consists of several building blocks that you can use on their own or together. The AgentCore CLI is the command-line tool for it: it generates projects, manages these building blocks and takes care of deployment. Under the hood it uses AWS CDK, but you do not have to operate CDK yourself.

Four terms are enough to get started:

Runtime: the managed environment for your agent code. Every session gets its own isolated microVM (a very lightweight virtual machine).
Harness: an agent you describe through configuration only (model, prompt, tools). AgentCore then runs the agent loop itself, and you write no code.
Memory: storage for conversation histories and facts derived from them, so an agent can remember things across sessions.
Gateway: exposes APIs and Lambda functions as MCP tools (Model Context Protocol) for agents.

This article takes the path with your own code, which means a runtime. A harness is quicker to set up, but I want to understand what my agent does. Besides, you can later turn a harness into code with agentcore export harness if it becomes too limiting.

What is new in the AgentCore CLI 1.0?

The npm package @aws/agentcore has been around since February 2026 in preview and 0.x versions. According to the announcement, AWS rebuilt the CLI for 1.0: it starts faster, its commands follow one uniform structure, and it covers more resource types. When I tried it, these points stood out:

Commands are grouped into three sections: Project (create, dev, deploy, invoke …), Resources (runtime, harness, gateway, memory …) and Settings.
You can address existing resources directly by ID or ARN without adding them to a project first, for example with agentcore runtime invoke --id ….
The global options --region, --json and --debug work the same way on every command. That makes CI scripts much nicer.
If you run agentcore without arguments, an interactive terminal UI with menus and wizards starts.
You convert 0.x projects to the new format with agentcore migrate.

A practical note: when I read the online CLI reference, several places still described old options, such as agentcore import instead of migrate. For the first few weeks, rely on agentcore <command> --help instead. I checked every command in this article against version 1.0.1.

The five commands that take an agent from an empty folder all the way to the logs.

Prerequisites

Node.js 20.12 or newer (I used Node 22), plus npm.
An AWS account with valid credentials. You can check them with aws sts get-caller-identity.
IAM permissions for AgentCore and for the CDK bootstrap roles. In a sandbox account an admin role is fine; in company accounts, clarify this first.
Access to a Claude model in Amazon Bedrock. The template uses a Claude Sonnet model through a global inference profile.
No Docker: the TypeScript template is built as a ZIP package (CodeZip).

Install the AgentCore CLI and create a project

Step 1: Install the CLI

npm install -g @aws/agentcore
agentcore --version

You should see 1.0.1 or newer. If the command prints something entirely different, the old Python tool bedrock-agentcore-starter-toolkit is probably still on your path. It is also called agentcore. Uninstall it with pip, pipx or uv and open a new terminal. By the way, the CLI collects anonymous usage data. If you do not want that, switch it off like this:

agentcore config telemetry.enabled false

Step 2: Generate a project from the template

Without options, agentcore create starts a wizard that creates a harness by default. For an agent with your own TypeScript code, specify the template explicitly. My example is the book advisor for the fictional bookstore “Bücherfuchs” (German for “book fox”):

agentcore create --name buecherfuchs --template agent-typescript-strands
cd buecherfuchs

The template agent-typescript-strands uses Strands Agents, the open-source framework from AWS. There is also a variant with the Vercel AI SDK (agent-typescript-vercel) and several Python templates. Afterwards the project looks like this (shortened):

buecherfuchs/
├── agentcore/
│   ├── agentcore.json      # What gets deployed: runtimes, memory, gateways ...
│   ├── aws-targets.json    # Target accounts and regions
│   ├── .env.local          # Variables for local development (gitignored)
│   └── cdk/                # Generated CDK project
└── app/
    └── agent/
        ├── main.ts         # Entry point of the agent
        ├── model/load.ts   # Which model is used
        └── memory/memory.ts

The central file is agentcore/agentcore.json. It lists which resources belong to the project. During deployment, the CLI translates it into a CDK stack. You add your own AWS resources, such as a DynamoDB table, in agentcore/cdk/lib/cdk-stack.ts – the generated file even contains an example for that.

Step 3: Leave out memory for now

The Strands template automatically adds an AgentCore Memory with four strategies (facts, preferences, summaries, episodes). That is too much for a first agent: it costs extra, slows down the deployment, and makes it harder to see what the agent itself does. So I remove the memory for now:

agentcore remove memory --name agentMemory
rm -r app/agent/memory

You can bring it back later with agentcore add memory once your agent really needs to remember things.

Give the agent its own tools

Step 4: Two tools for the book catalog

A tool is a function the model is allowed to call. Based on name and description, the model decides when it needs a tool and supplies suitable arguments. Strands validates these arguments with a Zod schema. Our book advisor gets two tools: a catalog search and a stock check. I keep the catalog in code on purpose so the example runs without any other AWS services.

// app/agent/tools/catalog.ts
import { tool } from '@strands-agents/sdk';
import { z } from 'zod';

export type Book = {
  isbn: string;
  title: string;
  author: string;
  genre: string;
  priceEur: number;
  inStock: number;
};

// Demo catalog of the fictional bookstore "Bücherfuchs".
// In a real project this would be a DynamoDB table or an API.
export const BOOKS: Book[] = [
  { isbn: '978-3-0000-0001-1', title: 'Fog over Hamburg', author: 'Lena Brandt', genre: 'Crime', priceEur: 14.0, inStock: 3 },
  { isbn: '978-3-0000-0002-8', title: 'Cooking for Lazy People', author: 'Tom Achterberg', genre: 'Cookbook', priceEur: 22.5, inStock: 0 },
  { isbn: '978-3-0000-0003-5', title: 'Stars over Lapland', author: 'Mira Holm', genre: 'Novel', priceEur: 18.9, inStock: 7 },
  { isbn: '978-3-0000-0004-2', title: 'Serverless for Beginners', author: 'Jonas Weber', genre: 'Non-fiction', priceEur: 34.0, inStock: 2 },
];

export function searchBooks(query: string, genre?: string): Book[] {
  const q = query.trim().toLowerCase();
  return BOOKS.filter(
    (b) =>
      (q === '' || b.title.toLowerCase().includes(q) || b.author.toLowerCase().includes(q)) &&
      (!genre || b.genre.toLowerCase() === genre.toLowerCase()),
  );
}

export const searchBooksTool = tool({
  name: 'search_books',
  description:
    'Searches the catalog of the Bücherfuchs bookstore by title or author, optionally filtered by genre. ' +
    'Returns ISBN, title, author, genre, price in euros and stock.',
  inputSchema: z.object({
    query: z.string().describe('Search term for title or author, empty for all books'),
    genre: z.string().optional().describe('Optional genre, e.g. Crime, Novel, Cookbook, Non-fiction'),
  }),
  callback: async ({ query, genre }) => searchBooks(query, genre),
});

export const checkStockTool = tool({
  name: 'check_stock',
  description: 'Checks by ISBN how many copies of a book are in stock at the store.',
  inputSchema: z.object({
    isbn: z.string().describe('ISBN in the format 978-3-…'),
  }),
  callback: async ({ isbn }) => {
    const book = BOOKS.find((b) => b.isbn === isbn);
    return {
      found: book !== undefined,
      isbn,
      title: book?.title ?? null,
      inStock: book?.inStock ?? 0,
    };
  },
});

Two details matter to me. First, tool results have to be JSON-compatible. With an interface for Book, the TypeScript compiler reports an error; with a type it works. Second, the descriptions deserve care, because they are the actual prompt for tool selection. There is more on that in my article on tool descriptions for AI agents.

Step 5: The entry point main.ts

Replace main.ts completely. It starts a small HTTP server through BedrockAgentCoreApp, validates the request and streams the agent’s answer back piece by piece:

// app/agent/main.ts
import { BedrockAgentCoreApp } from 'bedrock-agentcore/runtime';
import { Agent } from '@strands-agents/sdk';
import { z } from 'zod';
import { loadModel } from './model/load.js';
import { searchBooksTool, checkStockTool } from './tools/catalog.js';

const SYSTEM_PROMPT = `
You are the friendly book advisor of the bookstore "Bücherfuchs".
Use search_books and check_stock before you say anything about books, prices or stock.
Never invent books. Answer briefly and in English.
`;

const requestSchema = z.object({
  prompt: z.string().min(1),
});

// One agent per session, so the conversation stays together
const agents = new Map<string, Agent>();

async function agentFor(sessionId: string): Promise<Agent> {
  let agent = agents.get(sessionId);
  if (!agent) {
    agent = new Agent({
      model: await loadModel(),
      systemPrompt: SYSTEM_PROMPT,
      tools: [searchBooksTool, checkStockTool],
    });
    agents.set(sessionId, agent);
  }
  return agent;
}

const app = new BedrockAgentCoreApp({
  invocationHandler: {
    requestSchema,
    async *process(payload, context) {
      const agent = await agentFor(context?.sessionId ?? 'local');
      for await (const event of agent.stream(payload.prompt)) {
        if (
          event.type === 'modelStreamUpdateEvent' &&
          event.event?.type === 'modelContentBlockDeltaEvent' &&
          event.event.delta?.type === 'textDelta'
        ) {
          yield { data: event.event.delta.text };
        }
      }
    },
  },
});

app.run({ port: parseInt(process.env.PORT ?? '8080', 10) });

The agent is created once per session and kept in a map. Because AgentCore gives every session its own microVM, the conversation history lives as long as the session does. For long-term memory across sessions, AgentCore Memory takes over. Which model is used is defined in app/agent/model/load.ts. Change the model ID there if you want a different model or region.

Step 6: Test the tool logic without a model

The search function is plain TypeScript, so I test it like plain TypeScript. That is fast and does not cost a single token:

// app/agent/tools/catalog.test.ts
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { searchBooks } from './catalog.js';

test('finds books by author', () => {
  const result = searchBooks('holm');
  assert.equal(result.length, 1);
  assert.equal(result[0].title, 'Stars over Lapland');
});

test('filters by genre', () => {
  const result = searchBooks('', 'Crime');
  assert.deepEqual(result.map((b) => b.isbn), ['978-3-0000-0001-1']);
});

test('returns an empty list for an unknown term', () => {
  assert.equal(searchBooks('unicorn').length, 0);
});

cd app/agent
node --import tsx --test tools/catalog.test.ts
npx tsc --noEmit
cd ../..

Expect three passing tests and a compiler run without output. tsx is already a dependency in the template.

Test locally with agentcore dev

Step 7: Start the development server

agentcore dev

This starts your agent with hot reload on port 8080 and collects traces locally (OpenTelemetry). With agentcore dev --mode browser, the Agent Inspector opens as well – a web UI for chatting and clicking through traces. A simple request is enough for the health check:

curl -s localhost:8080/ping
# {"status":"Healthy","time_of_last_update":...}

Step 8: Ask the local agent

In a second terminal, send a prompt to the local server. --runtime is important; otherwise the CLI stops and tells you to specify exactly one resource:

agentcore invoke --runtime agent --local \
  --payload '{"prompt":"Do you have any crime novels in stock?"}'

The agent calls Amazon Bedrock with your local AWS credentials. If they are missing or the region cannot be reached, you get an event: error in the stream instead of an answer. That is exactly what I saw in my test environment without AWS access: server, routing and tools worked, and only the model call failed. It is a good hint where to look when something goes wrong.

Deploy the agent to AWS with the AgentCore CLI

Step 9: Build and deploy

agentcore build
agentcore deploy
agentcore status

build compiles the code and generates the CloudFormation template. In my project, the stack AgentCore-buecherfuchs contained exactly three relevant resources: an IAM role, the matching policy and the runtime itself. On the first run, deploy automatically creates the target default in aws-targets.json from your current account and region, and bootstraps CDK if needed. Expect a few minutes for the first run. Afterwards, status shows what is deployed and in which state.

🎬 Flow of a call with agentcore invoke – this animated diagram only runs on my site: watch it on sascha-ms.de

Step 10: Call the deployed agent

agentcore invoke --runtime agent \
  --payload '{"prompt":"How much is Stars over Lapland and is it in stock?"}' \
  --session-id "customer-4711-$(date +%Y%m%d)-book-consultation"

With the same --session-id, follow-up questions end up in the same session and therefore with the same agent object. If you omit the option, the CLI creates a new session. In a real application you would of course not call the runtime through the CLI but via the SDK from your backend, for example from a Lambda function behind an API.

Step 11: Read logs and traces

agentcore logs runtime --name agent --since 30m --level error
agentcore traces runtime list --name agent --since 1h

The logs come from CloudWatch, and the traces show every model and tool call with its duration. With agents, traces are a must. Without them you cannot tell whether a wrong answer came from the prompt, the tool or the model. If you want to build on that and check systematically how well your agent works, my article on evaluating AI agents will help.

Move existing projects with agentcore migrate

Anyone who has worked with a 0.x version needs to convert their project. The format of agentcore.json jumps from version 1 to version 2. I tried it with a freshly generated 0.31.2 project. The process is pleasantly cautious:

Without --yes, agentcore migrate only writes a plan to agentcore/.cli/migrate/ and changes nothing.
The project has to live in a Git repository with a clean working tree. Otherwise the CLI refuses to migrate, so that you can review and undo everything with git diff.
Resources that are already deployed keep their names. Afterwards, agentcore.json contains "migratedFrom": "v1" so the CDK construct keeps using the old names.
In the generated CDK folder, the Jest configuration and the sample test disappear, among other things. Back up your own changes there beforehand.

git status            # must be clean
agentcore migrate     # show the plan only
agentcore migrate --yes
git diff --stat
agentcore deploy

My advice: migrate in a branch first and deploy to a test account before you touch production. The plan lists precisely which files change. Actually read it.

Common mistakes and how to avoid them

The wrong agentcore command on your path

The old Python toolkit and the new CLI share the same name. If options like --template are unknown, check with which agentcore which program you are actually running.

A harness instead of a code project

The interactive wizard suggests a harness by default. If you want to write code, pass --template. Otherwise you will wonder why there is no app folder.

Tool results that are not JSON

Date objects, class instances or interfaces without an index signature are rejected by the JSONValue type. Return flat objects and convert dates to ISO strings.

Forgotten resources after the experiment

Deleting the project folder deletes nothing in AWS. Always tear down through the CLI, as described below.

Costs, security and cleanup

The runtime is billed per second based on consumption, split into CPU and memory. According to the pricing page, no CPU time is charged while your agent is only waiting for the model or a tool. For agents that spend most of their time waiting, that is a big advantage. On top of that come the model tokens in Bedrock, CloudWatch logs and, if you use it, AgentCore Memory. Model costs are usually the biggest item. A budget alarm in the account never hurts, though.

On security: the CLI creates a dedicated IAM role for the runtime. When your agent later needs other services, grant permissions specifically through the grant… methods in the CDK stack instead of broadly extending the role. Secrets and API keys do not belong in .env.local or in the code, but in AgentCore Identity (agentcore add credentials) or Secrets Manager.

Cleanup takes two steps. First you remove all resources from the project description, then the next deployment sees that nothing is left to deploy and removes the stack:

agentcore remove all --yes
agentcore deploy --yes

My take

To me, the AgentCore CLI 1.0 feels like what the Serverless Framework used to be for Lambda: it handles the scaffolding, and you take care of the logic. The path from create via dev to deploy is short, and I like that a normal CDK project sits underneath. I can look inside at any time and add my own resources without leaving the abstraction.

I see two things critically. The templates are rather generous: a memory with four strategies as the default is too much for a first agent and obscures the costs. In addition, the CLI documentation is currently lagging behind. That is normal after a major release, but annoying for teams that work from the docs. For new agent projects on AWS I would still use the CLI today. For existing 0.x projects I would plan the migration deliberately rather than doing it on the side.

And one more thing that matters to me: an agent does not become good just because it is deployed. The real work lies in good tools, clear boundaries and tests. The CLI only shortens the way there.

FAQ

What is the difference between the AgentCore CLI and the starter toolkit?

The starter toolkit was an older Python tool with the same command name. The AgentCore CLI is the current npm package @aws/agentcore and covers far more resources. Having both installed at the same time leads to confusion.

Do I need Docker for the AgentCore CLI?

No, not for the TypeScript templates and most Python templates. They are deployed as ZIP packages. You only need Docker, Podman or Finch for container templates and testing them locally.

Can I use models other than Claude with the AgentCore CLI?

Yes. The model is set in model/load.ts, where you can enter a different Bedrock model. According to their descriptions, several templates also support other model providers.

How much does an agent in the AgentCore Runtime cost?

You pay per second for the runtime’s CPU and memory, plus model tokens and logs. According to AWS, no CPU time is charged during pure waiting time. Current prices per region are on the AgentCore pricing page.

Your next step

Install the CLI, generate the Bücherfuchs project and replace the catalog with something from your own life, such as a list of your favorite recipes or running routes. Test locally first, then deploy to a sandbox account and tear everything down at the end. After that you will know whether the runtime path suits you or a harness is enough. I am curious: do you prefer building your agents with your own code or purely through configuration – and why?

Sources

This post was created with AI assistance.

👉 Next step: Working with AWS CDK? Grab my printable AWS CDK cheat sheet with commands, concepts and a stack skeleton.

Originally published on sascha-ms.de. More articles on serverless, AI in everyday development and leading tech teams: sascha-ms.de/en

DynamoDB TTL: build seat holds that expire

Sascha Mirow-Stanitzok — Sun, 01 Nov 2026 07:34:03 +0000

With DynamoDB TTL you can clean up expired items for free – and that is exactly why people like to use it for something it cannot do: releasing a seat right on time after ten minutes. I keep running into this misunderstanding whenever shopping carts, appointment bookings or ticket sales come up. The code looks clean, the tests are green, and in production holds suddenly stay stuck for hours.

So in this seventh part of the series I build holds with an expiry time the way I would build them today: the expiry lives in conditional writes, and TTL only cleans up. As an example, I use the ticket shop of a small cabaret theatre, and this time the infrastructure comes with the Serverless Framework. The pattern fits right in with the saga pattern from part 6: there, holds lock resources until the saga is done – and here we make sure that a stuck saga does not block anything forever.

In short

DynamoDB TTL does not delete expired items on time but eventually – according to AWS typically within a few days. That is why holds expire through their own expiry time and conditional writes; TTL and the stream only clean up afterwards. The biggest pitfall is code that silently waits for the deletion.

What you will learn in this article

What DynamoDB TTL guarantees and what it does not
How to hold seats all-or-nothing with a transaction
Why the expiry check belongs in the ConditionExpression
How TTL deletions in the stream help with cleanup
A runnable project with the Serverless Framework and TypeScript

Why a hold needs an expiry time

Picture the ticket shop: someone picks seats B7 and B8 for the improv show on Saturday and lands in the payment step. From that moment on, nobody else may get those seats. At the same time it would be fatal to block them forever just because someone closes the browser tab or cannot find their credit card.

Chris Richardson calls such techniques “countermeasures” in his description of the saga pattern – remedies for the missing isolation of distributed workflows (microservices.io). One of them is the semantic lock: a record gets a state like “held” that other workflows respect. However, every lock has the same problem: it must reliably go away again. A lock without an expiry time is a support ticket waiting to happen.

The obvious idea is: “I just set the TTL to ten minutes and the item is gone.” That is exactly where the trouble starts. So let us first look at what TTL in DynamoDB actually promises.

What DynamoDB TTL can do – and what it cannot

TTL stands for “time to live”. You enable it per table and name an attribute in which each item carries its expiry time. According to the AWS documentation, this value must be of type Number and contain Unix epoch time in seconds. The TTL process simply ignores other data types.

The decisive sentence sits right next to it: expired items are typically deleted within a few days after their expiry. Not after seconds, not after minutes, but eventually. Until then, however, the item stays readable as usual, shows up in Query and Scan results and can even still be modified.

Expectation	Reality according to AWS
Item disappears exactly at the TTL time	Deleted at some point afterwards, typically within a few days
Expired items are invisible	They show up in Query and Scan until deleted – you filter them yourself
Deleting costs write capacity	The TTL deletion consumes no write throughput (exception: replication in global tables)
Deletions look like any other in the stream	In the stream they carry the userIdentity of the service dynamodb.amazonaws.com

The expiry time decides right away, the TTL deletion comes eventually.

This leads to the rule the rest of the article revolves around: with DynamoDB TTL there are two clocks. The first one is your business expiry time, which you check yourself on every read and write. In contrast, the second one is the DynamoDB cleanup process, and no piece of business logic may rely on it.

The pattern: expiry time for the logic, TTL for cleanup

The pattern consists of three rules. First: every hold carries an attribute expiresAt, and every decision “free or taken?” compares this attribute with the current time. Second: these comparisons live in the ConditionExpression of the write so that DynamoDB checks them atomically. Third: a separate attribute ttl makes sure that forgotten items disappear eventually.

Why two attributes if both start with the same value? Because they have different jobs. For instance, when a hold is confirmed, it should be kept as a purchase record. Then you remove ttl but leave expiresAt as information. Besides, you can later extend the cleanup period – for example to keep expired holds around for a day for debugging – without touching the logic.

The data model in one table

Specifically, we need two kinds of items in one shared table. A seat item describes one seat of a performance and carries the hold when needed. A hold item describes the hold itself: which seats, until when, in which state.

pk	sk	Attributes	Purpose
SHOW#impro-2026-11-14	SEAT#B7	holdId, holdExpiresAt, soldTo	Seat with a semantic lock
HOLD#	HOLD	showId, seats, holdStatus, expiresAt, ttl	Hold, TTL for cleanup only

What matters is what is missing here: seat items never get a TTL attribute. Otherwise DynamoDB would eventually delete the seat itself, and the seating plan would have a hole. The lock on the seat expires solely via holdExpiresAt.

🎬 Flow: hold, confirm, clean up – this animated diagram only runs on my site: watch it on sascha-ms.de

Step by step: building holds with DynamoDB TTL

Now it gets concrete. We build a small HTTP API with three endpoints for holding, confirming and listing seats, plus a Lambda function that cleans up after TTL deletions.

Prerequisites

Node.js 22 or newer and npm
an AWS account with credentials for a test environment
Serverless Framework v4 (npm i -g serverless), it asks for a login or license key on the first deploy
basic knowledge of Lambda and DynamoDB

Step 1: Create the project

mkdir ticket-holds && cd ticket-holds
npm init -y
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb @aws-sdk/util-dynamodb
npm install -D typescript @types/aws-lambda @types/node

Afterwards the package.json looks roughly like this. We need the scripts later for type checking, tests and deploy:

{
  "name": "ticket-holds",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "typecheck": "tsc --noEmit",
    "test": "node --test test/*.test.ts",
    "deploy": "serverless deploy"
  },
  "dependencies": {
    "@aws-sdk/client-dynamodb": "^3.1159.0",
    "@aws-sdk/lib-dynamodb": "^3.1159.0",
    "@aws-sdk/util-dynamodb": "^3.996.9"
  },
  "devDependencies": {
    "@types/aws-lambda": "^8.10.164",
    "@types/node": "^22.0.0",
    "typescript": "^7.0.2"
  }
}

The tsconfig.json is set to noEmit because Serverless Framework v4 bundles TypeScript itself with esbuild during deploy. TypeScript is only used for type checking, and the tests run directly with Node, which strips types on its own these days.

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Preserve",
    "moduleResolution": "Bundler",
    "strict": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "erasableSyntaxOnly": true,
    "skipLibCheck": true,
    "types": ["node"]
  },
  "include": ["src", "test"]
}

Step 2: Table, stream and functions in serverless.yml

The table runs in on-demand mode, TTL is set to the attribute ttl, and the stream delivers the old image of deleted items. Without OLD_IMAGE the cleanup function would not know which seats belonged to the deleted hold.

# serverless.yml
service: ticket-holds
frameworkVersion: '4'

provider:
  name: aws
  runtime: nodejs22.x
  architecture: arm64
  region: eu-central-1
  memorySize: 512
  timeout: 10
  environment:
    TABLE_NAME: !Ref TicketTable
  iam:
    role:
      statements:
        - Effect: Allow
          Action:
            - dynamodb:GetItem
            - dynamodb:Query
            - dynamodb:PutItem
            - dynamodb:UpdateItem
          Resource: !GetAtt TicketTable.Arn

functions:
  createHold:
    handler: src/handlers/create-hold.handler
    events:
      - httpApi:
          method: POST
          path: /shows/{showId}/holds
  confirmHold:
    handler: src/handlers/confirm-hold.handler
    events:
      - httpApi:
          method: POST
          path: /holds/{holdId}/confirm
  listSeats:
    handler: src/handlers/list-seats.handler
    events:
      - httpApi:
          method: GET
          path: /shows/{showId}/seats
  releaseExpired:
    handler: src/handlers/release-expired.handler
    events:
      - stream:
          type: dynamodb
          arn: !GetAtt TicketTable.StreamArn
          startingPosition: LATEST
          batchSize: 25
          maximumRetryAttempts: 5
          filterPatterns:
            # only deleted hold items; the handler checks whether TTL deleted them
            - eventName: [REMOVE]
              dynamodb:
                Keys:
                  sk:
                    S: [HOLD]

resources:
  Resources:
    TicketTable:
      Type: AWS::DynamoDB::Table
      Properties:
        BillingMode: PAY_PER_REQUEST
        AttributeDefinitions:
          - AttributeName: pk
            AttributeType: S
          - AttributeName: sk
            AttributeType: S
        KeySchema:
          - AttributeName: pk
            KeyType: HASH
          - AttributeName: sk
            KeyType: RANGE
        TimeToLiveSpecification:
          AttributeName: ttl
          Enabled: true
        StreamSpecification:
          StreamViewType: OLD_IMAGE

The filter on the stream ensures that the cleanup function only starts for deleted hold items. Lambda can filter stream records by metadata such as eventName and by keys (Lambda docs). Whether TTL really did the deleting is checked by the handler itself as well – belt and braces.

Step 3: The core logic as pure functions

First of all, everything that builds DynamoDB expressions lives in one file without network access. In addition, the current time comes in as a parameter. As a result, every rule can be tested without an AWS account, and you can see at a glance which condition protects what.

// src/holds.ts
import type { TransactWriteCommandInput, UpdateCommandInput } from '@aws-sdk/lib-dynamodb';

/** How long a seat stays held: 10 minutes. */
export const HOLD_SECONDS = 10 * 60;

/** Seating plan of the small theatre: rows A to H, seats 1 to 20. */
const SEAT_PATTERN = /^[A-H](?:[1-9]|1[0-9]|20)$/;
const MAX_SEATS_PER_HOLD = 8;

export type SeatState = 'FREE' | 'HELD' | 'SOLD';

export interface HoldItem {
  pk: string;
  sk: 'HOLD';
  showId: string;
  seats: string[];
  holdStatus: 'ACTIVE' | 'CONFIRMED';
  expiresAt: number;
  ttl?: number;
}

export const nowInSeconds = (): number => Math.floor(Date.now() / 1000);

export const seatKey = (showId: string, seatId: string) => ({ pk: `SHOW#${showId}`, sk: `SEAT#${seatId}` });
export const holdKey = (holdId: string) => ({ pk: `HOLD#${holdId}`, sk: 'HOLD' as const });

export function validateSeats(input: unknown): string[] {
  if (!Array.isArray(input) || input.length === 0 || input.length > MAX_SEATS_PER_HOLD) {
    throw new Error(`Please request 1 to ${MAX_SEATS_PER_HOLD} seats.`);
  }
  const seats = [...new Set(input)];
  if (seats.length !== input.length) throw new Error('A seat is listed twice.');
  for (const seat of seats) {
    if (typeof seat !== 'string' || !SEAT_PATTERN.test(seat)) throw new Error(`Unknown seat: ${String(seat)}`);
  }
  return seats as string[];
}

/** Holds all seats or none: one transaction made of seat updates and the hold item. */
export function buildHoldTransaction(
  tableName: string, showId: string, holdId: string, seats: string[], now: number,
): TransactWriteCommandInput {
  const expiresAt = now + HOLD_SECONDS;
  const seatUpdates = seats.map((seatId) => ({
    Update: {
      TableName: tableName,
      Key: seatKey(showId, seatId),
      UpdateExpression: 'SET holdId = :holdId, holdExpiresAt = :expiresAt',
      // A seat is free if it is not sold and carries no valid hold.
      ConditionExpression:
        'attribute_not_exists(soldTo) AND (attribute_not_exists(holdExpiresAt) OR holdExpiresAt <= :now)',
      ExpressionAttributeValues: { ':holdId': holdId, ':expiresAt': expiresAt, ':now': now },
      ReturnValuesOnConditionCheckFailure: 'ALL_OLD' as const,
    },
  }));
  const holdItem: HoldItem = {
    ...holdKey(holdId), showId, seats, holdStatus: 'ACTIVE', expiresAt,
    ttl: expiresAt, // for cleanup only, not for the logic
  };
  return {
    TransactItems: [
      ...seatUpdates,
      { Put: { TableName: tableName, Item: holdItem, ConditionExpression: 'attribute_not_exists(pk)' } },
    ],
  };
}

/** Turns the hold into a purchase – only while it is still valid. */
export function buildConfirmTransaction(
  tableName: string, holdId: string, hold: Pick<HoldItem, 'showId' | 'seats'>, now: number,
): TransactWriteCommandInput {
  return {
    TransactItems: [
      {
        Update: {
          TableName: tableName,
          Key: holdKey(holdId),
          UpdateExpression: 'SET holdStatus = :confirmed, confirmedAt = :now REMOVE #ttl',
          ConditionExpression: 'holdStatus = :active AND expiresAt > :now',
          ExpressionAttributeNames: { '#ttl': 'ttl' },
          ExpressionAttributeValues: { ':confirmed': 'CONFIRMED', ':active': 'ACTIVE', ':now': now },
        },
      },
      ...hold.seats.map((seatId) => ({
        Update: {
          TableName: tableName,
          Key: seatKey(hold.showId, seatId),
          UpdateExpression: 'SET soldTo = :holdId REMOVE holdId, holdExpiresAt',
          ConditionExpression: 'holdId = :holdId AND attribute_not_exists(soldTo)',
          ExpressionAttributeValues: { ':holdId': holdId },
        },
      })),
    ],
  };
}

/** Frees a seat, but only if it still belongs to exactly this hold. */
export function buildSeatRelease(tableName: string, showId: string, seatId: string, holdId: string): UpdateCommandInput {
  return {
    TableName: tableName,
    Key: seatKey(showId, seatId),
    UpdateExpression: 'REMOVE holdId, holdExpiresAt',
    ConditionExpression: 'holdId = :holdId',
    ExpressionAttributeValues: { ':holdId': holdId },
  };
}

/** Read side: expiry is judged by the clock, not by the TTL deletion. */
export function seatState(item: { soldTo?: string; holdExpiresAt?: number } | undefined, now: number): SeatState {
  if (item?.soldTo) return 'SOLD';
  if (item?.holdExpiresAt !== undefined && item.holdExpiresAt > now) return 'HELD';
  return 'FREE';
}

/** Maps the CancellationReasons of a failed transaction to the requested seats. */
export function takenSeats(reasons: { Code?: string }[] | undefined, seats: string[]): string[] {
  if (!reasons) return [];
  return seats.filter((_, index) => reasons[index]?.Code === 'ConditionalCheckFailed');
}

export function allSeatIds(): string[] {
  const rows = 'ABCDEFGH'.split('');
  return rows.flatMap((row) => Array.from({ length: 20 }, (_, i) => `${row}${i + 1}`));
}

The most important line is the condition when holding: a seat is free if it is not sold and either carries no lock at all or its holdExpiresAt is no longer in the future. So an expired but not yet deleted hold blocks nobody. The transaction groups all seat updates and the hold item, so either all seats get held or none.

According to AWS, a TransactWriteItems request can bundle up to 100 actions with an aggregate size of at most 4 MB. With at most eight seats plus the hold item we stay far below that. Still, keep the cost in mind: DynamoDB performs every write in a transaction twice internally, once to prepare and once to commit.

Step 4: Hold seats

// src/db.ts
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';

export const TABLE_NAME = process.env.TABLE_NAME ?? '';
export const doc = DynamoDBDocumentClient.from(new DynamoDBClient({}));

export const json = (statusCode: number, body: unknown) => ({
  statusCode,
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify(body),
});

// src/handlers/create-hold.ts
import { randomUUID } from 'node:crypto';
import type { APIGatewayProxyEventV2, APIGatewayProxyResultV2 } from 'aws-lambda';
import { TransactionCanceledException } from '@aws-sdk/client-dynamodb';
import { TransactWriteCommand } from '@aws-sdk/lib-dynamodb';
import { doc, json, TABLE_NAME } from '../db.ts';
import { buildHoldTransaction, HOLD_SECONDS, nowInSeconds, takenSeats, validateSeats } from '../holds.ts';

export const handler = async (event: APIGatewayProxyEventV2): Promise<APIGatewayProxyResultV2> => {
  const showId = event.pathParameters?.showId ?? '';
  let seats: string[];
  try {
    seats = validateSeats(JSON.parse(event.body ?? '{}').seats);
  } catch (error) {
    return json(400, { message: (error as Error).message });
  }

  const holdId = randomUUID();
  const now = nowInSeconds();
  try {
    await doc.send(new TransactWriteCommand(buildHoldTransaction(TABLE_NAME, showId, holdId, seats, now)));
  } catch (error) {
    if (error instanceof TransactionCanceledException) {
      const taken = takenSeats(error.CancellationReasons, seats);
      if (taken.length > 0) return json(409, { message: 'These seats are not available right now.', seats: taken });
    }
    throw error; // Throttling or conflict: API Gateway returns 500, the client may retry
  }

  return json(201, { holdId, seats, expiresAt: new Date((now + HOLD_SECONDS) * 1000).toISOString() });
};

If the transaction fails on a condition, DynamoDB returns a TransactionCanceledException with a list of reasons – in the same order as the actions. Because the seat updates come first, takenSeats can tell directly which seats are taken right now. That is worth its weight in gold for the UI: instead of “error” it can say “sorry, B8 is gone”.

Step 5: Confirm the hold

// src/handlers/confirm-hold.ts
import type { APIGatewayProxyEventV2, APIGatewayProxyResultV2 } from 'aws-lambda';
import { TransactionCanceledException } from '@aws-sdk/client-dynamodb';
import { GetCommand, TransactWriteCommand } from '@aws-sdk/lib-dynamodb';
import { doc, json, TABLE_NAME } from '../db.ts';
import { buildConfirmTransaction, holdKey, nowInSeconds, type HoldItem } from '../holds.ts';

export const handler = async (event: APIGatewayProxyEventV2): Promise<APIGatewayProxyResultV2> => {
  const holdId = event.pathParameters?.holdId ?? '';
  const { Item } = await doc.send(new GetCommand({ TableName: TABLE_NAME, Key: holdKey(holdId), ConsistentRead: true }));
  const hold = Item as HoldItem | undefined;
  const now = nowInSeconds();

  if (!hold) return json(404, { message: 'Hold not found.' });
  if (hold.holdStatus === 'CONFIRMED') return json(200, { holdId, status: 'CONFIRMED' }); // a repeated call is harmless
  if (hold.expiresAt <= now) return json(410, { message: 'The hold has expired.' });

  try {
    await doc.send(new TransactWriteCommand(buildConfirmTransaction(TABLE_NAME, holdId, hold, now)));
  } catch (error) {
    if (error instanceof TransactionCanceledException) {
      return json(410, { message: 'The hold has expired or was already used.' });
    }
    throw error;
  }
  return json(200, { holdId, status: 'CONFIRMED', seats: hold.seats });
};

When confirming, the transaction checks two things: the hold is still active and expiresAt lies in the future, and every seat still belongs to exactly this hold. At the same time it removes ttl so that DynamoDB does not clean up the purchase record later. A second call with the same hold simply returns the confirmed state – the same idea as with idempotent Lambda handlers.

Admittedly, the upfront check with GetCommand is only there for friendly error messages. The actual safety comes from the condition in the transaction, because time can run out between reading and writing.

Step 6: Show the seating plan

// src/handlers/list-seats.ts
import type { APIGatewayProxyEventV2, APIGatewayProxyResultV2 } from 'aws-lambda';
import { QueryCommand } from '@aws-sdk/lib-dynamodb';
import { doc, json, TABLE_NAME } from '../db.ts';
import { allSeatIds, nowInSeconds, seatKey, seatState } from '../holds.ts';

export const handler = async (event: APIGatewayProxyEventV2): Promise<APIGatewayProxyResultV2> => {
  const showId = event.pathParameters?.showId ?? '';
  const { Items = [] } = await doc.send(new QueryCommand({
    TableName: TABLE_NAME,
    KeyConditionExpression: 'pk = :pk AND begins_with(sk, :seat)',
    ExpressionAttributeValues: { ':pk': seatKey(showId, '').pk, ':seat': 'SEAT#' },
  }));
  const bySeat = new Map(Items.map((item) => [String(item.sk).slice('SEAT#'.length), item]));
  const now = nowInSeconds();
  const seats = allSeatIds().map((seatId) => ({ seatId, state: seatState(bySeat.get(seatId), now) }));
  return json(200, { showId, seats });
};

The read side also judges the time itself. For Query and Scan, the AWS docs recommend a filter expression that sorts out expired items. Here a comparison in code is enough, because we load all seats of a performance anyway and compute a state.

Step 7: Clean up after the TTL deletion

// src/handlers/release-expired.ts
import type { DynamoDBStreamEvent } from 'aws-lambda';
import { ConditionalCheckFailedException } from '@aws-sdk/client-dynamodb';
import { UpdateCommand } from '@aws-sdk/lib-dynamodb';
import { unmarshall } from '@aws-sdk/util-dynamodb';
import type { AttributeValue } from '@aws-sdk/client-dynamodb';
import { doc, TABLE_NAME } from '../db.ts';
import { buildSeatRelease, type HoldItem } from '../holds.ts';

/** Cleans up seats after DynamoDB TTL has deleted an expired hold. */
export const handler = async (event: DynamoDBStreamEvent): Promise<void> => {
  for (const record of event.Records) {
    const deletedByTtl = record.eventName === 'REMOVE' && record.userIdentity?.principalId === 'dynamodb.amazonaws.com';
    const oldImage = record.dynamodb?.OldImage;
    if (!deletedByTtl || !oldImage) continue;

    const hold = unmarshall(oldImage as Record<string, AttributeValue>) as HoldItem;
    if (hold.sk !== 'HOLD' || hold.holdStatus !== 'ACTIVE') continue;
    const holdId = hold.pk.slice('HOLD#'.length);

    for (const seatId of hold.seats) {
      try {
        await doc.send(new UpdateCommand(buildSeatRelease(TABLE_NAME, hold.showId, seatId, holdId)));
      } catch (error) {
        // Seat already belongs to a new hold or is sold: nothing to do.
        if (!(error instanceof ConditionalCheckFailedException)) throw error;
      }
    }
  }
};

When TTL deletes a hold, a REMOVE event appears in the stream with userIdentity.type “Service” and principalId “dynamodb.amazonaws.com”. The function then removes the lock from the seats – but only if the same holdId is still there. If someone else has held or bought the seat in the meantime, the condition fails, and that is fine.

In fact, this function is purely cosmetic. If it is down for a day, the shop still sells correctly, because every decision goes through holdExpiresAt. That is exactly what sets this pattern apart from the outbox pattern, where the stream carries the actual work.

Step 8: Test and deploy

// test/holds.test.ts
import { test } from 'node:test';
import assert from 'node:assert/strict';
import {
  buildConfirmTransaction, buildHoldTransaction, HOLD_SECONDS, seatState, takenSeats, validateSeats,
} from '../src/holds.ts';

const NOW = 1_800_000_000;

test('hold sets expiry time and TTL to the same moment', () => {
  const tx = buildHoldTransaction('Tickets', 'impro-2026-11-14', 'h-1', ['A1', 'A2'], NOW);
  const items = tx.TransactItems ?? [];
  assert.equal(items.length, 3);
  const put = items[2].Put!;
  assert.equal(put.Item?.expiresAt, NOW + HOLD_SECONDS);
  assert.equal(put.Item?.ttl, NOW + HOLD_SECONDS);
  assert.match(items[0].Update!.ConditionExpression!, /holdExpiresAt <= :now/);
});

test('confirming checks the expiry time and removes the TTL', () => {
  const tx = buildConfirmTransaction('Tickets', 'h-1', { showId: 'impro-2026-11-14', seats: ['A1'] }, NOW);
  const holdUpdate = tx.TransactItems![0].Update!;
  assert.match(holdUpdate.ConditionExpression!, /expiresAt > :now/);
  assert.match(holdUpdate.UpdateExpression!, /REMOVE #ttl/);
  assert.equal(tx.TransactItems![1].Update!.ExpressionAttributeValues![':holdId'], 'h-1');
});

test('expired but not yet deleted hold counts as free', () => {
  assert.equal(seatState({ holdExpiresAt: NOW - 1 }, NOW), 'FREE');
  assert.equal(seatState({ holdExpiresAt: NOW + 60 }, NOW), 'HELD');
  assert.equal(seatState({ soldTo: 'h-1' }, NOW), 'SOLD');
  assert.equal(seatState(undefined, NOW), 'FREE');
});

test('failed transaction names the taken seats', () => {
  const reasons = [{ Code: 'None' }, { Code: 'ConditionalCheckFailed' }, { Code: 'None' }];
  assert.deepEqual(takenSeats(reasons, ['A1', 'A2']), ['A2']);
});

test('invalid seats are rejected', () => {
  assert.deepEqual(validateSeats(['B7', 'B8']), ['B7', 'B8']);
  assert.throws(() => validateSeats(['Z99']), /Unknown seat/);
  assert.throws(() => validateSeats(['A1', 'A1']), /twice/);
  assert.throws(() => validateSeats([]), /1 to 8/);
});

Moreover, the tests run without AWS access. Start them via the scripts from package.json or directly:

npx tsc --noEmit
node --test test/*.test.ts
serverless deploy

Expected result: five green tests and, after the deploy, output with the URL of your HTTP API. Then try it by hand:

API=https://abc123.execute-api.eu-central-1.amazonaws.com
curl -s -X POST "$API/shows/impro-2026-11-14/holds" -H "content-type: application/json" -d '{"seats":["B7","B8"]}'
# {"holdId":"4f1c…","seats":["B7","B8"],"expiresAt":"2026-10-29T19:10:00.000Z"}
curl -s -X POST "$API/shows/impro-2026-11-14/holds" -H "content-type: application/json" -d '{"seats":["B8","B9"]}'
# {"message":"These seats are not available right now.","seats":["B8"]}
curl -s -X POST "$API/holds/4f1c…/confirm"

If you wait longer than ten minutes after the first call, confirming returns status 410, and B7 and B8 can be booked again right away – regardless of whether DynamoDB has already deleted the hold item or not.

Common mistakes with DynamoDB TTL

Milliseconds instead of seconds. Date.now() returns milliseconds. If that value ends up in the TTL attribute, the expiry lies millennia in the future, and the item stays forever. So calculate with Math.floor(Date.now() / 1000) everywhere and wrap it in a function like nowInSeconds.

Storing the time as a string. An ISO date in the TTL attribute looks tidy but gets ignored, because TTL only evaluates the Number type. For display purposes you are welcome to store a readable date in addition.

TTL on the wrong item. If you put the TTL attribute on the seat instead of the hold, you will eventually delete master data. Therefore the rule is simple: TTL belongs on items whose complete disappearance is fine from a business point of view.

Waiting for the stream event. A notification “your hold has expired” that is only sent after the TTL deletion may arrive two days late. If you need timely reactions, schedule them explicitly, for example with EventBridge Scheduler and a one-time schedule per hold.

Clocks without a buffer. Lambda functions run on synchronized clocks, yet I would still show the UI a slightly shorter remaining time than the real one. Anyone who sees “30 seconds left” in the browser should not already have expired on the server.

Cost and security

The TTL deletion itself costs no write capacity, but until they are gone, expired items keep adding to your storage bill and read costs. Transactions cost twice as much as simple writes, which hardly matters for a ticket shop. If you are still wondering whether DynamoDB is the right store here at all, the AWS service finder helps you compare.

On security: the functions only get GetItem, Query, PutItem and UpdateItem on exactly this table – transactions check permissions per action. The API is open in this example; in real life it needs authentication in front of it and a limit on how many holds an account may keep at the same time. Otherwise a script holds the entire house within a minute, over and over again.

My take

I like this pattern because it hard-wires an uncomfortable truth: distributed systems do not clean up on time. If you accept that, you build logic that copes with leftovers instead of logic that waits for a cleanup crew. The condition in the write is where correctness comes from – everything else is convenience.

I would push back on the common advice to always use a separate lock table or a lock library for locks. For a resource that is its own item anyway, the lock on the item itself is enough. An extra table only pays off when you lock things that do not live in DynamoDB, such as a job in a third-party system.

FAQ

How fast does DynamoDB TTL delete expired items?

There is no fixed deadline. Instead, AWS describes the deletion as happening “typically within a few days” after expiry. So never plan with a specific point in time.

Does deleting via TTL cost write capacity?

No, the TTL deletion consumes no write throughput. Only with global tables does replicating the deletion to other regions cost write units.

Can I set the TTL attribute in milliseconds?

No. The value must be a Unix time in seconds of type Number. A millisecond value would still be a number, but it would lie so far in the future that the item practically never expires.

How do I recognize TTL deletions in the DynamoDB stream?

By the field userIdentity: it has the type “Service” and the principalId “dynamodb.amazonaws.com”. Regular deletions by your code do not have this field.

Your next step

Search your own code for TTL attributes and ask yourself for each one: does a business decision depend on the item disappearing? If so, add an expiry time to the condition – usually a small change with a big effect. And I am curious: where do you use locks with an expiry time, and which pitfalls have you run into? Feel free to share in the comments.

More in this series: Previous part: Saga pattern with Step Functions · Next part: Webhook retries with SQS and Lambda · All parts of the series “Serverless patterns in practice”

Sources

This post was created with AI assistance.

👉 Next step: Not sure which AWS service fits your use case? My AWS service finder asks a few questions and points you to the right one.

Originally published on sascha-ms.de. More articles on serverless, AI in everyday development and leading tech teams: sascha-ms.de/en

Remote onboarding checklist: the first 30 days

Sascha Mirow-Stanitzok — Sat, 31 Oct 2026 17:50:04 +0000

A good remote onboarding checklist decides whether new team members feel at home after four weeks or are still wondering who they are actually allowed to ask. In the office, everyday life smooths over a lot: you sit next to someone, overhear conversations, get invited to lunch. Remotely, all of that disappears. Anyone who gets nothing but a laptop and a wiki link on day one ends up alone in front of a screen, guessing.

This topic matters to me because the first weeks set the tone for the entire working relationship. So here is a plan for the first 30 days: what should happen before the first working day, what the first week looks like, what an onboarding buddy actually does, and how you can tell after a month whether it worked. On top of that, you get the complete checklist as a printable PDF.

In short

Remote onboarding works when you plan three things at once: access to knowledge, confidence with the tools and real relationships within the team. The key insight: remotely, relationships rarely form on the side, so you have to arrange them. The biggest pitfall is a first week made up of nothing but accounts, forms and documentation.

What you will learn in this article

What should be done before the first working day
How to plan the first week day by day
What an onboarding buddy does and how often you meet
How to recognize a good first task
Which questions belong in the 30-day conversation

Why remote onboarding needs its own checklist

Onboarding covers everything that helps a new team member settle into the company and the team: professionally, organizationally and personally. That goes beyond classic job training, where someone gets the tools explained. In the office, a large part of it happens by chance. Remotely, on the other hand, only what someone deliberately plans actually happens.

The GitLab Handbook, one of the most detailed public collections on distributed work, distinguishes three levels of remote onboarding: organizational (where do I find information?), technical (how do I use the tools?) and social (how do I build relationships?). I find this split helpful because it reveals a typical imbalance. The first two levels fit nicely into checklists and tickets, so they usually get done thoroughly. The social level feels soft and therefore tends to slip down the list.

Yet that is exactly where the feeling of belonging comes from. If, after three weeks, someone knows nobody on the team they can “just quickly” ask, they work more slowly and start doubting their decision to take the job sooner. A remote onboarding checklist therefore has to cover all three levels, right from the start.

The first 30 days at a glance: from preparation to the 30-day conversation

Remote onboarding checklist for the week before

The first working day really starts a week earlier. Everything you prepare here takes pressure off day one. Nothing drags on more than a start where your new colleague waits three hours for VPN access, wondering whether everyone forgot about her.

Hardware and access

Make sure the laptop arrives on time, with enough buffer for shipping and customs if someone lives abroad. Set up the accounts that are actually needed on day one: email, chat, calendar, video call tool, ticket system and wiki. Further access, for example to production systems, can come later. A short “Your first login” guide listing the steps in the right order also helps, because setting up multi-factor authentication and a password manager can otherwise easily eat half the morning.

People and calendar

Pick an onboarding buddy and ask whether they really have time during the first two weeks. Then pre-fill the calendar for week one: your first 1:1, the team meeting, two or three get-to-know-you sessions and plenty of free blocks for reading and setting up. A packed calendar looks caring, but for new people it is exhausting. Leave too much breathing room rather than too little.

Finally, send a short welcome message: when things start on day one, which link leads to the first call, who the buddy is and that nobody expects results on the first day. That sounds trivial. Even so, this very message removes the biggest uncertainty before the start, namely what is actually going to happen on Monday at nine.

Week 1: arriving, not delivering

The first week is about arriving. The new person should get to know the tools, be able to put names to the first faces and understand what the team is currently working on. Contributing productively is not expected yet. Say that explicitly, because many new team members put themselves under pressure to show something quickly.

Here is what a first week can look like:

Day	Focus	In practice
Monday	Welcome and setup	Welcome in the team call (15 minutes), setting up access, first call with the buddy in the afternoon
Tuesday	The team and its work	First 1:1 with you, overview of product and architecture, joining the daily as a listener
Wednesday	Tools and workflows	Setting up the development environment, walking through the path from ticket to deployment once
Thursday	Getting to know people	Two get-to-know-you sessions, a pairing session with someone from the team
Friday	Looking back	Short check-in with you: what helped, what is missing, what is unclear?

The most important meeting of the week is the buddy call at the end of day one. After eight hours full of new impressions, you need someone who asks: “How was it? What stuck, what didn’t?” The GitLab Handbook explicitly calls this first call the most important task of the buddy.

Your first 1:1 with the new person deserves its own preparation. How to structure it and which questions you can ask is covered in the guide to the first one-on-one, the first part of this series.

The get-to-know-you list

A simple tool with a big impact is a get-to-know-you list. You write down five to eight people the new team member should meet during the first month, each with one sentence explaining why. For example: “Jana, product owner – knows why the current feature is built the way it is” or “Malik, operations – helps you when a deployment gets stuck”. The new person then schedules the meetings themselves.

This has two advantages. First, conversations get a clear reason, which is easier for reserved people in particular than an open “Let me know if you need anything”. Second, the new person learns how people approach each other on your team. Give the people on the list a heads-up beforehand so they are not caught off guard.

The onboarding buddy: tasks and rhythm

An onboarding buddy is a colleague from the team who is the first point of contact for all the small questions during the first weeks. They are not a manager and they do not evaluate anything. Their job is to make sure nobody is left alone with a question they don’t dare to ask.

The GitLab Handbook describes a clear rhythm: the first call on day one, then at least two more calls in the first week and at least one more during the rest of the first month. In addition, it recommends asking the new person whether they want more or fewer meetings. I consider this point important, since some people want a short daily chat while others prefer one longer conversation per week.

Who to choose as a buddy

Among its criteria, GitLab lists: at least three months with the company, the same department, a similar time zone and availability during the first two weeks. I would add one more: the buddy should actually want to do it. Someone who only takes on the role because nobody else is around will quickly start cancelling meetings. Also plan a backup in case the buddy gets sick or goes on vacation.

The time spent in the buddy role is real work. Expect a few hours during the first weeks and plan them into the sprint instead of expecting them to happen on the side. Otherwise, the buddy has to choose between their own tasks and the new colleague, and usually both lose.

Week 2: the first real task

In the second week, things can get concrete. The first task of their own is an important moment, because it shows that the new person is really needed. At the same time, it tests your processes: how long does it take for a small change to go live? Where does it get stuck?

A good first task is small enough to finish in two or three days, yet still covers the whole path from ticket through review to deployment. For example, a small improvement to an error message, a missing test or a gap in the documentation noticed during onboarding itself. Unsuitable, on the other hand, are tasks that require diving deep into unfamiliar code, or urgent tasks that create time pressure.

Plan at least one pairing session in which someone from the team works on the task together with the new person. Remotely, this replaces looking over someone’s shoulder. It is also worth explicitly inviting the new person to fix documentation whenever they run into gaps. New people spot gaps that everyone else stopped noticing long ago.

Weeks 3 and 4: responsibility grows

From the third week on, onboarding gradually turns into regular teamwork. The new person joins all rituals, picks up tickets from the regular backlog and no longer just listens in the daily. Which rituals hold a remote team together is something I describe in detail in the article Leading remote teams: rituals that actually work.

During this phase, pay particular attention to quiet signals. Is the person asking fewer questions than at the beginning because they have understood everything, or because they no longer dare to? Remotely, you won’t see it in their face at the coffee machine. So ask directly in the 1:1 whether there are things that are still unclear but now “feel weird to ask”. This phrasing opens a door surprisingly often.

The 30-day conversation

After one month, a dedicated conversation that goes beyond the regular 1:1 is worth it. It has two goals: finding out how the new person is doing, and learning how to improve your onboarding. These questions work well as a framework:

What helped you most during the first weeks?
When did you first feel like part of the team?
What surprised you, positively or negatively?
Which question haven’t you dared to ask so far?
What should we do differently in the next onboarding?
What do you need from me over the next 60 days?

The answers to the second-to-last question are pure gold. Write them down and adjust your remote onboarding checklist accordingly. That way, onboarding gets a little better with every new team member.

Common mistakes in remote onboarding

The most common mistake is a first week made up of nothing but forms, mandatory training and documentation. All of that is necessary, but if nobody has asked the new person how they are doing by Friday, one feeling sticks above all: here, I am just a case file.

A second classic is “Let me know if you need anything”. It is meant kindly. In practice, though, it puts all the responsibility on the person who knows least about what they need and whom they can ask. Scheduled meetings and the get-to-know-you list solve this better.

Third: too much at once. Anyone who gets twelve intro calls, three training sessions and the complete architecture explained in the first week retains very little of it. Spread the content across the month and allow time to process what was heard.

And finally: no wrap-up. If onboarding simply fizzles out, you miss the moment when you look back together. The 30-day conversation closes this gap and at the same time gives you the feedback you need for the next onboarding.

My take

I consider onboarding one of the most underrated leadership tasks of all. A lot of energy goes into selecting new people, into job ads and interviews. Once the signature is in, however, things often go quiet, and the first working day becomes a task for the IT department.

Yet you will never again get as much honest feedback about your team as during a new member’s first weeks. New people see what has long become normal for everyone else: unclear processes, outdated documentation, unwritten rules. Make use of that instead of smoothing it over.

I want to push back on the idea that remote onboarding is inherently worse than onboarding in the office. It is different and requires more planning. In return, it forces you to write down things that otherwise only live in people’s heads. In the end, the whole team benefits, not just the new colleague.

FAQ

How long does remote onboarding take?

For actually settling in, 30 days is a good frame. Until someone works truly independently within the team, it takes considerably longer depending on the role. So keep regular 1:1s going after the first month as well.

What belongs in a remote onboarding checklist?

At a minimum: hardware and access before day one, a pre-planned calendar for week one, an onboarding buddy, a get-to-know-you list, a small first task with pairing and a wrap-up conversation after 30 days.

How often should an onboarding buddy check in?

A proven rhythm: one call on day one, two more in the first week and at least one more until the end of the month. Ask the new person whether this pace suits them.

Who is responsible for onboarding?

The manager is responsible and plans the framework. The buddy, the team and the new person shape it together. Organizational matters such as hardware and accounts can be handled by IT or HR.

Your next step

Take the checklist and go through it for the next person who joins your team. If nobody is starting right now, ask the team member who joined most recently: what would have helped you during your first 30 days? The answers will show you very precisely where your onboarding has gaps today.

I’m curious how you handle it: what was the best thing that happened to you in a remote onboarding? Feel free to share it in the comments.

Continue the series: Back to the “Leadership in brief” overview · Previous part: Leading remote teams with rituals that work. Next part: Offboarding: when someone leaves the team.

📄 Printable cheat sheet – The complete 30-day remote onboarding checklist to tick off – with buddy rhythm and questions for the 30-day conversation. Download PDF · View online

Sources

This post was created with AI assistance.

👉 Next step: Preparing a first one-on-one? My question cheat sheet puts the best questions on one printable page.

Originally published on sascha-ms.de. More articles on serverless, AI in everyday development and leading tech teams: sascha-ms.de/en