AWS Lambda JSON: Events, Responses, and API Gateway Integration

Written and reviewed by the Jsonic editorial team — every guide is verified against the official spec or runtime before publication.

Last updated: May 19, 2026

AWS Lambda handles JSON at every layer: the event object delivered by the runtime, the response shape expected by API Gateway, and the event structures from S3, SQS, and DynamoDB Streams. Each trigger has a distinct JSON schema, and several have subtle gotchas — particularly API Gateway's requirement that the response body be a string, not an object. This guide covers all of them with working TypeScript and Python examples.

Lambda Handler Structure and Event Parsing

The Lambda runtime deserializes the trigger payload into a JSON object before calling your handler. For API Gateway proxy integration, the HTTP request body arrives inside event.body as a raw string — you must parse it yourself.

import type { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda'

export const handler = async (
  event: APIGatewayProxyEvent
): Promise<APIGatewayProxyResult> => {
  // API Gateway passes body as a JSON string
  if (!event.body) {
    return { statusCode: 400, body: JSON.stringify({ error: 'Missing body' }) }
  }

  let payload: { name: string; email: string }
  try {
    payload = JSON.parse(event.body)
  } catch {
    return { statusCode: 400, body: JSON.stringify({ error: 'Invalid JSON' }) }
  }

  const result = { id: Date.now(), name: payload.name, email: payload.email }

  return {
    statusCode: 201,
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(result),
  }
}

Python equivalent:

import json

def handler(event, context):
    # API Gateway proxy: body is a JSON string
    body_str = event.get('body', '{}')
    try:
        body = json.loads(body_str)
    except json.JSONDecodeError:
        return {
            'statusCode': 400,
            'body': json.dumps({'error': 'Invalid JSON body'}),
        }

    name = body.get('name', 'World')
    return {
        'statusCode': 200,
        'headers': {'Content-Type': 'application/json'},
        'body': json.dumps({'message': f'Hello, {name}!'}),
    }

API Gateway Proxy Response Structure

API Gateway requires a specific JSON shape from your Lambda. The body field must always be a string — pass it through JSON.stringify() before returning.

{
  "statusCode": 200,
  "headers": {
    "Content-Type": "application/json",
    "Access-Control-Allow-Origin": "*"
  },
  "body": "{\"message\": \"Success\", \"id\": 42}",
  "isBase64Encoded": false
}

S3 Event Structure

S3 events deliver bucket and object metadata in event.Records. Decode the object key before using it — S3 URL-encodes special characters and replaces spaces with +.

import { S3Event } from 'aws-lambda'
import { S3Client, GetObjectCommand } from '@aws-sdk/client-s3'

const s3 = new S3Client({})

export const handler = async (event: S3Event) => {
  for (const record of event.Records) {
    const bucket = record.s3.bucket.name
    const key = decodeURIComponent(record.s3.object.key.replace(/\+/g, ' '))

    // Fetch the JSON file that was uploaded
    const response = await s3.send(new GetObjectCommand({ Bucket: bucket, Key: key }))
    const bodyStr = await response.Body?.transformToString('utf-8')
    if (!bodyStr) continue

    const data = JSON.parse(bodyStr) as Record<string, unknown>
    console.log('Processed:', key, 'keys:', Object.keys(data).length)
  }
}

Key S3 event JSON fields:

{
  "Records": [{
    "eventSource": "aws:s3",
    "eventName": "ObjectCreated:Put",
    "s3": {
      "bucket": { "name": "my-bucket", "arn": "arn:aws:s3:::my-bucket" },
      "object": {
        "key": "uploads/data.json",
        "size": 1024,
        "eTag": "abc123"
      }
    }
  }]
}

SQS Event Structure

SQS delivers messages in event.Records, where each record.body is a string — even when the original message was JSON. Parse it individually and handle errors carefully to avoid redriving entire batches.

import { SQSEvent } from 'aws-lambda'

interface OrderEvent {
  orderId: string
  customerId: string
  total: number
  items: Array<{ productId: string; qty: number }>
}

export const handler = async (event: SQSEvent) => {
  for (const record of event.Records) {
    let order: OrderEvent
    try {
      order = JSON.parse(record.body) as OrderEvent
    } catch {
      console.error('Invalid SQS message body:', record.body)
      continue  // skip — don't throw (avoids redrive loop for bad messages)
    }

    console.log(`Processing order ${order.orderId} for customer ${order.customerId}`)
    await processOrder(order)
  }
}

// Note: if your Lambda throws for a message, SQS will retry it up to maxReceiveCount
// Partial batch failure: return { batchItemFailures: [{ itemIdentifier: record.messageId }] }

DynamoDB JSON and Streams

DynamoDB Streams deliver items in DynamoDB JSON — a typed format where each value is wrapped with its type descriptor. Use unmarshall() from @aws-sdk/util-dynamodb to convert to plain JavaScript objects.

import { DynamoDBStreamEvent } from 'aws-lambda'
import { unmarshall } from '@aws-sdk/util-dynamodb'

// DynamoDB stores items in DynamoDB JSON format (typed attribute values)
// { "id": { "S": "123" }, "age": { "N": "30" } }
// unmarshall() converts to plain JS: { id: "123", age: 30 }

export const handler = async (event: DynamoDBStreamEvent) => {
  for (const record of event.Records) {
    if (record.eventName === 'INSERT' && record.dynamodb?.NewImage) {
      const item = unmarshall(record.dynamodb.NewImage as Record<string, any>)
      console.log('New item:', JSON.stringify(item, null, 2))
    }
    if (record.eventName === 'REMOVE' && record.dynamodb?.OldImage) {
      const removed = unmarshall(record.dynamodb.OldImage as Record<string, any>)
      console.log('Deleted:', removed.id)
    }
  }
}

Environment Variables and JSON Config

Lambda environment variables are always strings. Store JSON config as a serialized string and parse it once at module level so the parsed object is reused across warm invocations.

// Lambda env vars are strings — parse JSON config at cold start
const CONFIG = JSON.parse(process.env.APP_CONFIG ?? '{}') as {
  dbHost: string
  cacheTimeout: number
  featureFlags: Record<string, boolean>
}

// Lazy-parsed (re-used across warm invocations)
export const handler = async (event: unknown) => {
  if (CONFIG.featureFlags.betaFeature) {
    // use beta feature
  }
  return { statusCode: 200, body: JSON.stringify({ host: CONFIG.dbHost }) }
}

// In Lambda console or SAM template:
// APP_CONFIG = {"dbHost":"db.internal","cacheTimeout":300,"featureFlags":{"betaFeature":true}}

Common Lambda JSON Pitfalls and Solutions

// CORS-enabled response helper
function jsonResponse(statusCode: number, body: unknown, cors = true): APIGatewayProxyResult {
  return {
    statusCode,
    headers: {
      'Content-Type': 'application/json',
      ...(cors ? { 'Access-Control-Allow-Origin': '*' } : {}),
    },
    body: JSON.stringify(body),
  }
}

FAQ

Definitions

event object

The JSON-parsed input passed to a Lambda handler; shape depends on the trigger (API Gateway, S3, SQS, DynamoDB Streams, EventBridge); always inspect the raw event JSON in CloudWatch logs when debugging.

proxy integration

API Gateway mode where the full HTTP request (headers, body, path, method) is forwarded to Lambda as a JSON event; the Lambda must return a specific JSON response shape with statusCode, headers, and body as a string.

DynamoDB JSON

A JSON encoding that annotates each value with its DynamoDB type descriptor (S, N, BOOL, L, M, NULL); the @aws-sdk/util-dynamodb package provides marshall/unmarshall helpers to convert between DynamoDB JSON and plain JavaScript objects.

batchItemFailures

Partial batch response format for SQS Lambda triggers; return a list of failed messageIds so only those messages are retried rather than the entire batch, preventing good messages from being reprocessed.

cold start

The latency penalty when Lambda initializes a new execution environment; module-level code (including JSON.parse of env vars) runs once per cold start and is cached for subsequent warm invocations.