> Part of the walkerOS documentation. Project overview and full index: [Server](#)[ ](https://github.com/elbwalker/walkerOS/tree/main/packages/server/sources/aws) [Source code](https://github.com/elbwalker/walkerOS/tree/main/packages/server/sources/aws)[ ](https://www.npmjs.com/package/@walkeros/server-source-aws) [Package](https://www.npmjs.com/package/@walkeros/server-source-aws) # AWS Lambda AWS Lambda source for walkerOS. Works across API Gateway REST (v1), API Gateway HTTP (v2), Lambda Function URLs, and direct invocation. Auto-detects the API Gateway version, supports optional pixel tracking with a 1x1 GIF response, and exposes a built-in health check endpoint. The `@walkeros/server-source-aws` package also ships [`sourceSqs`](https://www.walkeros.io/docs/sources/server/sqs.md) for ingesting from SQS queues; this page covers the Lambda handler only. Where this fits The AWS Lambda source is a **server source** in the walkerOS flow: It receives events via HTTP and forwards them to your destinations. ## Installation[​](#installation "Direct link to Installation") ``` npm install @walkeros/server-source-aws ``` * Integrated * Bundled ``` import { sourceLambda } from '@walkeros/server-source-aws'; import { startFlow } from '@walkeros/collector'; let handler: any; async function init() { if (handler) return handler; const { sources } = await startFlow({ sources: { lambda: { code: sourceLambda, config: { settings: { cors: true, healthPath: '/health' }, }, }, }, destinations: { // Your destinations }, }); handler = sources.lambda.push; return handler; } export const main = async (event: any, context: any) => { const h = await init(); return h(event, context); }; export { main as handler }; ``` Add to your `flow.json` sources: ``` "sources": { "lambda": { "package": "@walkeros/server-source-aws", "config": { "settings": { "cors": true, "healthPath": "/health" } } } } ``` Server sources require platform-specific handlers. For containerized deployments, see [Docker](https://www.walkeros.io/docs/apps/docker.md). [See bundled mode setup](https://www.walkeros.io/docs/getting-started/modes/bundled.md) | [CLI reference](https://www.walkeros.io/docs/apps/cli.md) ## Configuration[​](#configuration "Direct link to Configuration") This source uses the standard source config wrapper (consent, data, env, id, ...). For the shared fields see [source configuration](https://www.walkeros.io/docs/sources.md#configuration). Package-specific fields live under `config.settings` and are listed below. ## Settings[​](#settings "Direct link to Settings") | Property | Type | Description | More | | --------------------- | ------------------- | --------------------------------------------------------------------------------------------- | ---- | | `cors` | `boolean \| object` | CORS configuration: false = disabled, true = allow all origins, object = custom configuration | | | `timeout` | `integer` | Request timeout in milliseconds (max: 900000 for Lambda) | | | `enablePixelTracking` | `boolean` | Enable GET requests with 1x1 transparent GIF response for pixel tracking | | | `maxBatchSize` | `integer` | Maximum number of events accepted in a single batch request | | | `healthPath` | `string` | Health check endpoint path (e.g., /health) | | ## Mapping[​](#mapping "Direct link to Mapping") This package does not define custom rule-level settings. For the standard rule fields (consent, condition, data, batch, name, policy) see [mapping](https://www.walkeros.io/docs/mapping.md). ## Examples ### API Gateway v1 POST A REST API Gateway v1 POST request with a JSON body is converted into a walker elb event. Event ``` { "httpMethod": "POST", "path": "/collect", "requestContext": { "requestId": "req-789", "identity": { "sourceIp": "203.0.113.42" } }, "queryStringParameters": null, "body": "{\"name\":\"page view\",\"data\":{\"title\":\"Home\"}}", "isBase64Encoded": false } ``` Out ``` elb({ "name": "page view", "data": { "title": "Home" } }) ``` ### Lambda GET An API Gateway v2 HTTP GET with query parameters is parsed into an elb event payload. Event ``` { "version": "2.0", "requestContext": { "http": { "method": "GET", "path": "/collect" }, "requestId": "req-456" }, "rawQueryString": "e=page+view&d=%7B%22title%22%3A%22Home%22%7D", "isBase64Encoded": false } ``` Out ``` elb({ "e": "page view", "d": "{\"title\":\"Home\"}" }) ``` ### Lambda POST An API Gateway v2 HTTP POST with a JSON body is converted into a walker elb event. Event ``` { "version": "2.0", "requestContext": { "http": { "method": "POST", "path": "/collect" }, "requestId": "req-123" }, "body": "{\"name\":\"page view\",\"data\":{\"title\":\"Home\"}}", "isBase64Encoded": false } ``` Out ``` elb({ "name": "page view", "data": { "title": "Home" } }) ``` ### Lambda POST with provenance A POST body carrying a source map is forwarded in full, so release and trace provenance survive the crossing. Event ``` { "version": "2.0", "requestContext": { "http": { "method": "POST", "path": "/collect" }, "requestId": "req-321" }, "body": "{\"name\":\"page view\",\"data\":{\"title\":\"Home\"},\"source\":{\"release\":{\"web\":\"r1\"}}}", "isBase64Encoded": false } ``` Out ``` elb({ "name": "page view", "data": { "title": "Home" }, "source": { "release": { "web": "r1" } } }) ``` ## Request format[​](#request-format "Direct link to Request format") The event name field is `name`. Every other field of the body is forwarded to the collector as-is, so `source` (carrying `release` and `trace` provenance) rides through instead of being dropped. ``` { "name": "page view", "data": { "title": "Home Page", "path": "/" } } ``` ## Responses[​](#responses "Direct link to Responses") | Status | Meaning | | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | 200 | Event processed | | 400 | Rejected client input: the pipeline declared the event invalid. The body echoes the validation message, for example `Event name is required` | | 500 | The pipeline failed to process a valid event, or an unexpected server fault | Invalid input is counted on `collector.status.sources..rejected` rather than inflating `status.failed`, and is logged at warn with the reason instead of as an error with a stack trace. ## Ingest metadata[​](#ingest-metadata "Direct link to Ingest metadata") Extract request metadata from Lambda events and forward it through the pipeline. `config.ingest` must use the `map` operator. Keys are output field names; values are paths on the shared [request scope](https://www.walkeros.io/docs/sources/scope.md), with no prefix. A bare object like `{ ip: 'ip' }` is silently inert: without the `map` operator the source passes the whole scope through and no field is extracted. **API Gateway v1 and v2 produce an identical scope.** The version specific envelopes are normalized away, so one mapping serves both. ``` const { sources } = await startFlow({ sources: { lambda: { code: sourceLambda, config: { settings: { cors: true }, ingest: { map: { ip: { key: 'ip' }, ua: { key: 'headers.user-agent' }, path: { key: 'path' }, }, }, }, }, }, }); ``` ### Available ingest paths[​](#available-ingest-paths "Direct link to Available ingest paths") | Path | Description | | ---------------- | -------------------------------------------------------- | | `method` | Uppercase HTTP method, both gateway versions | | `url` | Absolute request URL, when a `host` header is present | | `path` | Pathname, no query string | | `query.` | Query parameter, repeated keys joined with `,` | | `headers.` | Header, lowercased name, repeated values joined with `,` | | `body` | Parsed body, base64 decoded when the event says so | | `ip` | Client IP, from either gateway version's request context | | `raw` | The Lambda event itself | Anything genuinely version specific stays reachable through `raw`, for example `raw.requestContext.stage`. ## Supported platforms[​](#supported-platforms "Direct link to Supported platforms") | Platform | Status | | ------------------------- | --------- | | API Gateway REST API (v1) | Supported | | API Gateway HTTP API (v2) | Supported | | Lambda Function URLs | Supported | | Direct Lambda invocation | Supported |