Lambda Powertools Idempotency: DynamoDB Keys That Survive Retries

import { makeIdempotent, IdempotencyConfig } from "@aws-lambda-powertools/idempotency";
import { DynamoDBPersistenceLayer } from "@aws-lambda-powertools/idempotency/dynamodb";

const persistence = new DynamoDBPersistenceLayer({ tableName: process.env.IDEMP_TABLE! });

// GOOD: stable across redelivery jitter (new eventId, same orderId)
const config = new IdempotencyConfig({
 eventKeyJmesPath: "detail.orderId",
 expiresAfterSeconds: 60 * 60 * 24, // 24h > client retry + DLQ
 useLocalCache: true,
 throwOnNoIdempotencyKey: true,
});

async function charge(event: { detail: { orderId: string; amount: number } }) {
 return { charged: event.detail.amount, orderId: event.detail.orderId };
}

export const handler = makeIdempotent(charge, { persistenceStore: persistence, config });

// BAD: whole-event hash — EventBridge envelope changes → duplicate charge
const badConfig = new IdempotencyConfig({
 eventKeyJmesPath: "@", // unique every delivery
 expiresAfterSeconds: 30, // shorter than client retry budget
});
void badConfig;

import type { APIGatewayProxyEventV2 } from "aws-lambda";

const httpConfig = new IdempotencyConfig({
 eventKeyJmesPath: 'headers."idempotency-key"',
 expiresAfterSeconds: 60 * 15,
 throwOnNoIdempotencyKey: true,
});

export const apiHandler = makeIdempotent(
 async (event: APIGatewayProxyEventV2) => {
 const body = JSON.parse(event.body ?? "{}");
 return { statusCode: 200, body: JSON.stringify(await createPayment(body)) };
 },
 { persistenceStore: persistence, config: httpConfig },
);

const deploySafe = new IdempotencyConfig({
 eventKeyJmesPath: "detail.orderId",
 // Include payload hash when handler semantics change across versions
 payloadValidationJmesPath: "detail",
 expiresAfterSeconds: 86_400,
});

// PK: id (idempotency key), attrs: expiration, status, data_hash, response_data
// Enable TTL on expiration attribute. Provision enough WCU for peak retry storms.