Skip to main content
Ask your AI
Server Source code Package

AWS Lambda

The AWS Lambda source for walkerOS works across API Gateway REST (v1), API Gateway HTTP (v2) and Lambda Function URLs. It detects the API Gateway version automatically, supports optional pixel tracking with a 1x1 GIF response, and has a built-in health check endpoint. The @walkeros/server-source-aws package also ships sourceSqs 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​

npm install @walkeros/server-source-aws
import { Source } from '@walkeros/core';
import { startFlow } from '@walkeros/collector';
import { sourceLambda, type SourceLambda } from '@walkeros/server-source-aws';

let handler: SourceLambda.Push | undefined;

async function setup(): Promise<SourceLambda.Push> {
  if (handler) return handler;

  const { collector } = await startFlow({
    sources: {
      lambda: {
        code: sourceLambda,
        config: {
          settings: {
            cors: true,
            enablePixelTracking: true,
            healthPath: '/health',
          },
        },
      },
    },
    destinations: {
      // Your destinations
    },
  });

  handler = Source.getSource<SourceLambda.Types>(collector, 'lambda').push;
  return handler;
}

export const main: SourceLambda.Push = async (event, context) => {
  const h = await setup();
  return h(event, context);
};

export { main as handler };

Configuration​

This source uses the standard source config wrapper (consent, data, env, id, ...). For the shared fields see source configuration. Package-specific fields live under config.settings and are listed below.

Settings​

PropertyTypeDescriptionMore
corsboolean | objectCORS configuration: false = disabled, true = allow all origins, object = custom configuration
timeoutintegerRequest timeout in milliseconds (max: 900000 for Lambda)
enablePixelTrackingbooleanEnable GET requests with 1x1 transparent GIF response for pixel tracking
maxBatchSizeintegerMaximum number of events accepted in a single batch request
healthPathstringHealth check endpoint path (e.g., /health)

Mapping​

This package does not define custom rule-level settings. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.

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 name and data[...] query parameters becomes a single walker elb event.

Event
{
  "version": "2.0",
  "requestContext": {
    "http": {
      "method": "GET",
      "path": "/collect"
    },
    "requestId": "req-456"
  },
  "rawQueryString": "name=page+view&data%5Btitle%5D=Home",
  "isBase64Encoded": false
}
Out
elb({
  "name": "page view",
  "data": {
    "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​

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​

StatusMeaning
200Event processed, or failed for a reason a resend cannot fix (see below)
400Rejected client input: the pipeline declared the event invalid (the body echoes the validation message, for example Event name is required), a POST without a body (Request body is required), or a batch larger than maxBatchSize
405Method not allowed, or GET with enablePixelTracking: false
500The pipeline failed to process a valid event for a reason a resend could fix (the body is Event was not processed), or an unexpected server fault (Internal server error)
207Batch request where at least one event was invalid or failed for a reason a resend could fix. The body carries per-index errors

Every request to healthPath (default /health) answers { status: 'ok', ... }, whatever the method.

A failed event is acknowledged or retried by one rule on every server source: see Producer acknowledgement.

Invalid input is counted on collector.status.sources.<id>.rejected rather than inflating status.failed, and is logged at error with the reason and no stack trace, once per source and minute. A POST without a body and a batch over maxBatchSize are answered 400 and not counted.

The source sets no body size limit of its own; Lambda caps a synchronous request payload at 6 MB.

settings.timeout has no effect today: a request whose push takes longer still waits for it and answers as above.

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, with no prefix. A bare object like { ip: 'ip' } has no operator: walkeros validate and the bundle reject it, and if it still runs, the collector logs one ERROR line (mapping value has no operator) 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 { collector } = await startFlow({
  sources: {
    lambda: {
      code: sourceLambda,
      config: {
        settings: { cors: true },
        ingest: {
          map: {
            ip: { key: 'ip' },
            userAgent: { key: 'headers.user-agent' },
            path: { key: 'path' },
          },
        },
      },
    },
  },
});

Available ingest paths​

PathDescription
methodUppercase HTTP method, both gateway versions
urlAbsolute request URL, when a host header is present
pathPathname, no query string
query.<name>Query parameter, repeated keys joined with ,
headers.<name>Header, lowercased name, repeated values joined with ,
bodyParsed body, base64 decoded when the event says so
ipClient IP, from either gateway version's request context
rawThe Lambda event itself

Anything version specific stays reachable through raw, for example raw.requestContext.stage.

Supported platforms​

PlatformStatus
API Gateway REST API (v1)Supported
API Gateway HTTP API (v2)Supported
Lambda Function URLsSupported
Direct Lambda invocationOnly with an API Gateway v1 or v2 shaped event
💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)