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

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 Security and auth model .

Function URL invocation basics

If your function URL uses the AWS_IAM auth type, you must sign each HTTP request using AWS Signature Version 4 (SigV4) . Tools such as awscurl , Postman , and AWS 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 AWS 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:

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

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

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"}

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 AWS Identity and Access Management (IAM).

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 .

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

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

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

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

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

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

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

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

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

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:

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

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.

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!"