Invoking Lambda function URLs - Amazon Lambda
Function URL invocation basicsRequest and response payloads
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Invoking Lambda function URLs

A function URL is a dedicated HTTP(S) endpoint for your Lambda function. You can create and configure a function URL through the Lambda console or the Lambda API. When you create a function URL, Lambda automatically generates a unique URL endpoint for you. Once you create a function URL, its URL endpoint never changes. Function URL endpoints have the following format:

https://<url-id>.lambda-url.<region>.on.aws
Note

Function URLs are not supported in the following Amazon Web Services Regions: Asia Pacific (Hyderabad) (ap-south-2), Asia Pacific (Melbourne) (ap-southeast-4), Asia Pacific (Malaysia) (ap-southeast-5), Canada West (Calgary) (ca-west-1), Europe (Spain) (eu-south-2), Europe (Zurich) (eu-central-2), Israel (Tel Aviv) (il-central-1), and Middle East (UAE) (me-central-1).

Function URLs are dual stack-enabled, supporting IPv4 and IPv6. After configuring your function URL, you can invoke your function through its HTTP(S) endpoint via a web browser, curl, Postman, or any HTTP client. To invoke a function URL, you must have lambda:InvokeFunctionUrl permissions. For more information, see Access control.

Function URL invocation basics

If your function URL uses the AWS_IAM auth type, you must sign each HTTP request using Amazon Signature Version 4 (SigV4). Tools such as awscurl, Postman, and Amazon SigV4 Proxy offer built-in ways to sign your requests with SigV4.

If you don't use a tool to sign HTTP requests to your function URL, you must manually sign each request using SigV4. When your function URL receives a request, Lambda also calculates the SigV4 signature. Lambda processes the request only if the signatures match. For instructions on how to manually sign your requests with SigV4, see Signing Amazon requests with Signature Version 4 in the Amazon Web Services General Reference Guide.

If your function URL uses the NONE auth type, you don't have to sign your requests using SigV4. You can invoke your function using a web browser, curl, Postman, or any HTTP client.

To test simple GET requests to your function, use a web browser. For example, if your function URL is https://abcdefg.lambda-url.us-east-1.on.aws, and it takes in a string parameter message, your request URL could look like this:

https://abcdefg.lambda-url.us-east-1.on.aws/?message=HelloWorld

To test other HTTP requests, such as a POST request, you can use a tool such as curl. For example, if you want to include some JSON data in a POST request to your function URL, you could use the following curl command:

curl -v 'https://abcdefg.lambda-url.us-east-1.on.aws/?message=HelloWorld' \
-H 'content-type: application/json' \
-d '{ "example": "test" }'

Request and response payloads

When a client calls your function URL, Lambda maps the request to an event object before passing it to your function. Your function's response is then mapped to an HTTP response that Lambda sends back to the client through the function URL.

The request and response event formats follow the same schema as the Amazon API Gateway payload format version 2.0.

Request payload format

A request payload has the following structure:

{
  "version": "2.0",
  "routeKey": "$default",
  "rawPath": "/my/path",
  "rawQueryString": "parameter1=value1&parameter1=value2&parameter2=value",
  "cookies": [
    "cookie1",
    "cookie2"
  ],
  "headers": {
    "header1": "value1",
    "header2": "value1,value2"
  },
  "queryStringParameters": {
    "parameter1": "value1,value2",
    "parameter2": "value"
  },
  "requestContext": {
    "accountId": "123456789012",
    "apiId": "<urlid>",
    "authentication": null,
    "authorizer": {
        "iam": {
                "accessKey": "AKIA...",
                "accountId": "111122223333",
                "callerId": "AIDA...",
                "cognitoIdentity": null,
                "principalOrgId": null,
                "userArn": "arn:aws:iam::111122223333:user/example-user",
                "userId": "AIDA..."
        }
    },
    "domainName": "<url-id>.lambda-url.us-west-2.on.aws",
    "domainPrefix": "<url-id>",
    "http": {
      "method": "POST",
      "path": "/my/path",
      "protocol": "HTTP/1.1",
      "sourceIp": "123.123.123.123",
      "userAgent": "agent"
    },
    "requestId": "id",
    "routeKey": "$default",
    "stage": "$default",
    "time": "12/Mar/2020:19:03:58 +0000",
    "timeEpoch": 1583348638390
  },
  "body": "Hello from client!",
  "pathParameters": null,
  "isBase64Encoded": false,
  "stageVariables": null
}
Parameter Description Example

version

The payload format version for this event. Lambda function URLs currently support payload format version 2.0.

2.0

routeKey

Function URLs don't use this parameter. Lambda sets this to $default as a placeholder.

$default

rawPath

The request path. For example, if the request URL is https://{url-id}.lambda-url.{region}.on.aws/example/test/demo, then the raw path value is /example/test/demo.

/example/test/demo

rawQueryString

The raw string containing the request's query string parameters. Supported characters include a-z, A-Z, 0-9, ., _, -, %, &, =, and +.

"?parameter1=value1&parameter2=value2"

cookies

An array containing all cookies sent as part of the request.

["Cookie_1=Value_1", "Cookie_2=Value_2"]

headers

The list of request headers, presented as key-value pairs.

{"header1": "value1", "header2": "value2"}

queryStringParameters

The query parameters for the request. For example, if the request URL is https://{url-id}.lambda-url.{region}.on.aws/example?name=Jane, then the queryStringParameters value is a JSON object with a key of name and a value of Jane.

{"name": "Jane"}

requestContext

An object that contains additional information about the request, such as the requestId, the time of the request, and the identity of the caller if authorized via Amazon Identity and Access Management (IAM).

requestContext.accountId

The Amazon Web Services account ID of the function owner.

"123456789012"

requestContext.apiId

The ID of the function URL.

"33anwqw8fj"

requestContext.authentication

Function URLs don't use this parameter. Lambda sets this to null.

null

requestContext.authorizer

An object that contains information about the caller identity, if the function URL uses the AWS_IAM auth type. Otherwise, Lambda sets this to null.

requestContext.authorizer.iam.accessKey

The access key of the caller identity.

"AKIAIOSFODNN7EXAMPLE"

requestContext.authorizer.iam.accountId

The Amazon Web Services account ID of the caller identity.

"111122223333"

requestContext.authorizer.iam.callerId

The ID (user ID) of the caller.

"AIDACKCEVSQ6C2EXAMPLE"

requestContext.authorizer.iam.cognitoIdentity

Function URLs don't use this parameter. Lambda sets this to null or excludes this from the JSON.

null

requestContext.authorizer.iam.principalOrgId

The principal org ID associated with the caller identity.

"AIDACKCEVSQORGEXAMPLE"

requestContext.authorizer.iam.userArn

The user Amazon Resource Name (ARN) of the caller identity.

"arn:aws:iam::111122223333:user/example-user"

requestContext.authorizer.iam.userId

The user ID of the caller identity.

"AIDACOSFODNN7EXAMPLE2"

requestContext.domainName

The domain name of the function URL.

"<url-id>.lambda-url.us-west-2.on.aws"

requestContext.domainPrefix

The domain prefix of the function URL.

"<url-id>"

requestContext.http

An object that contains details about the HTTP request.

requestContext.http.method

The HTTP method used in this request. Valid values include GET, POST, PUT, HEAD, OPTIONS, PATCH, and DELETE.

GET

requestContext.http.path

The request path. For example, if the request URL is https://{url-id}.lambda-url.{region}.on.aws/example/test/demo, then the path value is /example/test/demo.

/example/test/demo

requestContext.http.protocol

The protocol of the request.

HTTP/1.1

requestContext.http.sourceIp

The source IP address of the immediate TCP connection making the request.

123.123.123.123

requestContext.http.userAgent

The User-Agent request header value.

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Gecko/20100101 Firefox/42.0

requestContext.requestId

The ID of the invocation request. You can use this ID to trace invocation logs related to your function.

e1506fd5-9e7b-434f-bd42-4f8fa224b599

requestContext.routeKey

Function URLs don't use this parameter. Lambda sets this to $default as a placeholder.

$default

requestContext.stage

Function URLs don't use this parameter. Lambda sets this to $default as a placeholder.

$default

requestContext.time

The timestamp of the request.

"07/Sep/2021:22:50:22 +0000"

requestContext.timeEpoch

The timestamp of the request, in Unix epoch time.

"1631055022677"

body

The body of the request. If the content type of the request is binary, the body is base64-encoded.

{"key1": "value1", "key2": "value2"}

pathParameters

Function URLs don't use this parameter. Lambda sets this to null or excludes this from the JSON.

null

isBase64Encoded

TRUE if the body is a binary payload and base64-encoded. FALSE otherwise.

FALSE

stageVariables

Function URLs don't use this parameter. Lambda sets this to null or excludes this from the JSON.

null

Response payload format

When your function returns a response, Lambda parses the response and converts it into an HTTP response. Function response payloads have the following format:

{
   "statusCode": 201,
    "headers": {
        "Content-Type": "application/json",
        "My-Custom-Header": "Custom Value"
    },
    "body": "{ \"message\": \"Hello, world!\" }",
    "cookies": [
        "Cookie_1=Value1; Expires=21 Oct 2021 07:48 GMT",
        "Cookie_2=Value2; Max-Age=78000"
    ],
    "isBase64Encoded": false
}

Lambda infers the response format for you. If your function returns valid JSON and doesn't return a statusCode, Lambda assumes the following:

  • statusCode is 200.

  • content-type is application/json.

  • body is the function response.

  • isBase64Encoded is false.

The following examples show how the output of your Lambda function maps to the response payload, and how the response payload maps to the final HTTP response. When the client invokes your function URL, they see the HTTP response.

Example output for a string response

Lambda function output Interpreted response output HTTP response (what the client sees) 
"Hello, world!"
 
{
  "statusCode": 200,
  "body": "Hello, world!",
  "headers": {
    "content-type": "application/json"
  },
  "isBase64Encoded": false
}
 
HTTP/2 200
date: Wed, 08 Sep 2021 18:02:24 GMT
content-type: application/json
content-length: 15

"Hello, world!"

Example output for a JSON response

Lambda function output Interpreted response output HTTP response (what the client sees) 
{
  "message": "Hello, world!"
}
 
{
  "statusCode": 200,
  "body": {
    "message": "Hello, world!"
  },
  "headers": {
    "content-type": "application/json"
  },
  "isBase64Encoded": false
}
 
HTTP/2 200
date: Wed, 08 Sep 2021 18:02:24 GMT
content-type: application/json
content-length: 34

{
  "message": "Hello, world!"
}

Example output for a custom response

Lambda function output Interpreted response output HTTP response (what the client sees) 
{
   "statusCode": 201,
    "headers": {
        "Content-Type": "application/json",
        "My-Custom-Header": "Custom Value"
    },
    "body": JSON.stringify({
        "message": "Hello, world!"
    }),
    "isBase64Encoded": false
}
 
{
   "statusCode": 201,
    "headers": {
        "Content-Type": "application/json",
        "My-Custom-Header": "Custom Value"
    },
    "body": JSON.stringify({
        "message": "Hello, world!"
    }),
    "isBase64Encoded": false
}
 
HTTP/2 201
date: Wed, 08 Sep 2021 18:02:24 GMT
content-type: application/json
content-length: 27
my-custom-header: Custom Value

{
  "message": "Hello, world!"
}

Cookies

To return cookies from your function, don't manually add set-cookie headers. Instead, include the cookies in your response payload object. Lambda automatically interprets this and adds them as set-cookie headers in your HTTP response, as in the following example.

Lambda function output HTTP response (what the client sees) 
{
   "statusCode": 201,
    "headers": {
        "Content-Type": "application/json",
        "My-Custom-Header": "Custom Value"
    },
    "body": JSON.stringify({
        "message": "Hello, world!"
    }),
    "cookies": [
        "Cookie_1=Value1; Expires=21 Oct 2021 07:48 GMT",
        "Cookie_2=Value2; Max-Age=78000"
    ],
    "isBase64Encoded": false
}
 
HTTP/2 201
date: Wed, 08 Sep 2021 18:02:24 GMT
content-type: application/json
content-length: 27
my-custom-header: Custom Value
set-cookie: Cookie_1=Value2; Expires=21 Oct 2021 07:48 GMT
set-cookie: Cookie_2=Value2; Max-Age=78000

{
  "message": "Hello, world!"
}