# Creating and managing 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. **Tip** Lambda offers two ways to invoke your function through an HTTP endpoint: function URLs and Amazon API Gateway. If you're not sure which is the best method for your use case, see [Select a method to invoke your Lambda function using an HTTP request](furls-http-invoke-decision.md). 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://.lambda-url..on.aws ``` **Note** Function URLs are not supported in the following AWS Regions: Asia Pacific (Hyderabad) (`ap-south-2`), Asia Pacific (Melbourne) (`ap-southeast-4`), Asia Pacific (Malaysia) (`ap-southeast-5`), Asia Pacific (New Zealand) (`ap-southeast-6`), Asia Pacific (Thailand) (`ap-southeast-7`), Asia Pacific (Taipei) (`ap-east-2`), 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 you configure a function URL for your function, you can invoke your function through its HTTP(S) endpoint via a web browser, curl, Postman, or any HTTP client. **Note** You can access your function URL through the public Internet only. While Lambda functions do support AWS PrivateLink, function URLs do not. Lambda function URLs use [resource-based policies](access-control-resource-based.md) for security and access control. Function URLs also support cross-origin resource sharing (CORS) configuration options. You can apply function URLs to any function alias, or to the `$LATEST` unpublished function version. You can't add a function URL to any other function version. The following section show how to create and manage a function URL using the Lambda console, AWS CLI, and CloudFormation template **Topics** + [ ## Creating a function URL (console) ](#create-url-console) + [ ## Creating a function URL (AWS CLI) ](#create-url-cli) + [ ## Adding a function URL to a CloudFormation template ](#urls-cfn) + [ ## Cross-origin resource sharing (CORS) ](#urls-cors) + [ ## Throttling function URLs ](#urls-throttling) + [ ## Deactivating function URLs ](#urls-deactivating) + [ ## Deleting function URLs ](#w2aac39c81c53) + [ # Control access to Lambda function URLs ](urls-auth.md) + [ # Invoking Lambda function URLs ](urls-invocation.md) + [ # Monitoring Lambda function URLs ](urls-monitoring.md) + [ # Select a method to invoke your Lambda function using an HTTP request ](furls-http-invoke-decision.md) + [ # Tutorial: Creating a webhook endpoint using a Lambda function URL ](urls-webhook-tutorial.md) ## Creating a function URL (console) Follow these steps to create a function URL using the console. ### To create a function URL for an existing function 1. Open the [Functions page](https://console.aws.amazon.com/lambda/home#/functions) of the Lambda console. 1. Choose the name of the function that you want to create the function URL for. 1. Choose the **Configuration** tab, and then choose **Function URL**. 1. Choose **Create function URL**. 1. For **Auth type**, choose **AWS\$1IAM** or **NONE**. For more information about function URL authentication, see [Access control](urls-auth.md). 1. (Optional) Select **Configure cross-origin resource sharing (CORS)**, and then configure the CORS settings for your function URL. For more information about CORS, see [Cross-origin resource sharing (CORS)](#urls-cors). 1. Choose **Save**. This creates a function URL for the `$LATEST` unpublished version of your function. The function URL appears in the **Function overview** section of the console. ### To create a function URL for an existing alias 1. Open the [Functions page](https://console.aws.amazon.com/lambda/home#/functions) of the Lambda console. 1. Choose the name of the function with the alias that you want to create the function URL for. 1. Choose the **Aliases** tab, and then choose the name of the alias that you want to create the function URL for. 1. Choose the **Configuration** tab, and then choose **Function URL**. 1. Choose **Create function URL**. 1. For **Auth type**, choose **AWS\$1IAM** or **NONE**. For more information about function URL authentication, see [Access control](urls-auth.md). 1. (Optional) Select **Configure cross-origin resource sharing (CORS)**, and then configure the CORS settings for your function URL. For more information about CORS, see [Cross-origin resource sharing (CORS)](#urls-cors). 1. Choose **Save**. This creates a function URL for your function alias. The function URL appears in the console's **Function overview** section for your alias. ### To create a new function with a function URL **To create a new function with a function URL (console)** 1. Open the [Functions page](https://console.aws.amazon.com/lambda/home#/functions) of the Lambda console. 1. Choose **Create function**. 1. Under **Basic information**, do the following: 1. For **Function name**, enter a name for your function, such as **my-function**. 1. For **Runtime**, choose the language runtime that you prefer, such as **Node.js 24**. 1. For **Architecture**, choose either **x86\$164** or **arm64**. 1. Expand **Permissions**, then choose whether to create a new execution role or use an existing one. 1. Expand **Advanced settings**, and then select **Function URL**. 1. For **Auth type**, choose **AWS\$1IAM** or **NONE**. For more information about function URL authentication, see [Access control](urls-auth.md). 1. (Optional) Select **Configure cross-origin resource sharing (CORS)**. By selecting this option during function creation, your function URL allows requests from all origins by default. You can edit the CORS settings for your function URL after creating the function. For more information about CORS, see [Cross-origin resource sharing (CORS)](#urls-cors). 1. Choose **Create function**. This creates a new function with a function URL for the `$LATEST` unpublished version of the function. The function URL appears in the **Function overview** section of the console. ## Creating a function URL (AWS CLI) To create a function URL for an existing Lambda function using the AWS Command Line Interface (AWS CLI), run the following command: ``` aws lambda create-function-url-config \ --function-name my-function \ --qualifier prod \ // optional --auth-type AWS_IAM --cors-config {AllowOrigins="https://example.com"} // optional ``` This adds a function URL to the **prod** qualifier for the function **my-function**. For more information about these configuration parameters, see [CreateFunctionUrlConfig](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunctionUrlConfig.html) in the API reference. **Note** To create a function URL via the AWS CLI, the function must already exist. ## Adding a function URL to a CloudFormation template To add an `AWS::Lambda::Url` resource to your CloudFormation template, use the following syntax: ### JSON ``` { "Type" : "AWS::Lambda::Url", "Properties" : { "AuthType" : String, "Cors" : Cors, "Qualifier" : String, "TargetFunctionArn" : String } } ``` ### YAML ``` Type: AWS::Lambda::Url Properties: AuthType: String Cors: Cors Qualifier: String TargetFunctionArn: String ``` ### Parameters + (Required) `AuthType` – Defines the type of authentication for your function URL. Possible values are either `AWS_IAM` or `NONE`. To restrict access to authenticated users only, set to `AWS_IAM`. To bypass IAM authentication and allow any user to make requests to your function, set to `NONE`. + (Optional) `Cors` – Defines the [CORS settings](#urls-cors) for your function URL. To add `Cors` to your `AWS::Lambda::Url` resource in CloudFormation, use the following syntax. **Example AWS::Lambda::Url.Cors (JSON)** ``` { "AllowCredentials" : Boolean, "AllowHeaders" : [ String, ... ], "AllowMethods" : [ String, ... ], "AllowOrigins" : [ String, ... ], "ExposeHeaders" : [ String, ... ], "MaxAge" : Integer } ``` **Example AWS::Lambda::Url.Cors (YAML)** ``` AllowCredentials: Boolean AllowHeaders: - String AllowMethods: - String AllowOrigins: - String ExposeHeaders: - String MaxAge: Integer ``` + (Optional) `Qualifier` – The alias name. + (Required) `TargetFunctionArn` – The name or Amazon Resource Name (ARN) of the Lambda function. Valid name formats include the following: + **Function name** – `my-function` + **Function ARN** – `arn:aws:lambda:us-west-2:123456789012:function:my-function` + **Partial ARN** – `123456789012:function:my-function` ## Cross-origin resource sharing (CORS) To define how different origins can access your function URL, use [cross-origin resource sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS). We recommend configuring CORS if you intend to call your function URL from a different domain. Lambda supports the following CORS headers for function URLs. | CORS header | CORS configuration property | Example values | | --- | --- | --- | | [ Access-Control-Allow-Origin](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin) | `AllowOrigins` | `*` (allow all origins) `https://www.example.com` `http://localhost:60905` | | [ Access-Control-Allow-Methods](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Methods) | `AllowMethods` | `GET`, `POST`, `DELETE`, `*` | | [ Access-Control-Allow-Headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers) | `AllowHeaders` | `Date`, `Keep-Alive`, `X-Custom-Header` | | [ Access-Control-Expose-Headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Expose-Headers) | `ExposeHeaders` | `Date`, `Keep-Alive`, `X-Custom-Header` | | [ Access-Control-Allow-Credentials](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials) | `AllowCredentials` | `TRUE` | | [ Access-Control-Max-Age](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age) | `MaxAge` | `5` (default), `300` | When you configure CORS for a function URL using the Lambda console or the AWS CLI, Lambda automatically adds the CORS headers to all responses through the function URL. Alternatively, you can manually add CORS headers to your function response. If there are conflicting headers, the expected behavior depends on the type of request: + For preflight requests such as OPTIONS requests, the configured CORS headers on the function URL take precedence. Lambda returns only these CORS headers in the response. + For non-preflight requests such as GET or POST requests, Lambda returns both the configured CORS headers on the function URL, as well as the CORS headers returned by the function. This can result in duplicate CORS headers in the response. You may see an error similar to the following: `The 'Access-Control-Allow-Origin' header contains multiple values '*, *', but only one is allowed`. In general, we recommend configuring all CORS settings on the function URL, rather than sending CORS headers manually in the function response. ## Throttling function URLs Throttling limits the rate at which your function processes requests. This is useful in many situations, such as preventing your function from overloading downstream resources, or handling a sudden surge in requests. You can throttle the rate of requests that your Lambda function processes through a function URL by configuring reserved concurrency. Reserved concurrency limits the number of maximum concurrent invocations for your function. Your function's maximum request rate per second (RPS) is equivalent to 10 times the configured reserved concurrency. For example, if you configure your function with a reserved concurrency of 100, then the maximum RPS is 1,000. Whenever your function concurrency exceeds the reserved concurrency, your function URL returns an HTTP `429` status code. If your function receives a request that exceeds the 10x RPS maximum based on your configured reserved concurrency, you also receive an HTTP `429` error. For more information about reserved concurrency, see [Configuring reserved concurrency for a function](configuration-concurrency.md). ## Deactivating function URLs In an emergency, you might want to reject all traffic to your function URL. To deactivate your function URL, set the reserved concurrency to zero. This throttles all requests to your function URL, resulting in HTTP `429` status responses. To reactivate your function URL, delete the reserved concurrency configuration, or set the configuration to an amount greater than zero. ## Deleting function URLs When you delete a function URL, you can’t recover it. Creating a new function URL will result in a different URL address. **Note** If you delete a function URL with auth type `NONE`, Lambda doesn't automatically delete the associated resource-based policy. If you want to delete this policy, you must manually do so. 1. Open the [Functions page](https://console.aws.amazon.com/lambda/home#/functions) of the Lambda console. 1. Choose the name of the function. 1. Choose the **Configuration** tab, and then choose **Function URL**. 1. Choose **Delete**. 1. Enter the word *delete* into the field to confirm the deletion. 1. Choose **Delete**. **Note** When you delete a function that has a function URL, Lambda asynchronously deletes the function URL. If you immediately create a new function with the same name in the same account, it is possible that the original function URL will be mapped to the new function instead of deleted. # Control access to Lambda function URLs **Note** Starting in October 2025, new function URLs will require both `lambda:InvokeFunctionUrl` and `lambda:InvokeFunction` permissions. You can control access to your Lambda function URLs using the [AuthType](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunctionUrlConfig.html#lambda-CreateFunctionUrlConfig-request-AuthType) parameter combined with [resource-based policies](access-control-resource-based.md) attached to your specific function. The configuration of these two components determines who can invoke or perform other administrative actions on your function URL. The `AuthType` parameter determines how Lambda authenticates or authorizes requests to your function URL. When you configure your function URL, you must specify one of the following `AuthType` options: + `AWS_IAM` – Lambda uses AWS Identity and Access Management (IAM) to authenticate and authorize requests based on the IAM principal's identity policy and the function's resource-based policy. Choose this option if you want only authenticated users and roles to invoke your function using the function URL. + `NONE` – Lambda doesn't perform any authentication before invoking your function. However, your function's resource-based policy is always in effect and must grant public access before your function URL can receive requests. Choose this option to allow public, unauthenticated access to your function URL. For additional insights into security, you can use AWS Identity and Access Management Access Analyzer to get a comprehensive analysis of external access to your function URL. IAM Access Analyzer also monitors for new or updated permissions on your Lambda functions to help you identify permissions that grant public and cross-account access. You can use IAM Access Analyzer at no charge. To get started with IAM Access Analyzer, see [Using AWS IAM Access Analyzer](https://docs.aws.amazon.com/IAM/latest/UserGuide/what-is-access-analyzer.html). This page contains examples of resource-based policies for both auth types, and how to create these policies using the [AddPermission](https://docs.aws.amazon.com/lambda/latest/api/API_AddPermission.html) API operation or the Lambda console. For information about how to invoke your function URL after you've set up permissions, see [Invoking Lambda function URLs](urls-invocation.md). **Topics** + [ ## Using the `AWS_IAM` auth type ](#urls-auth-iam) + [ ## Using the `NONE` auth type ](#urls-auth-none) + [ ## Governance and access control ](#urls-governance) ## Using the `AWS_IAM` auth type If you choose the `AWS_IAM` auth type, users who need to invoke your Lambda function URL must have the `lambda:InvokeFunctionUrl` and `lambda:InvokeFunction` permissions. Depending on who makes the invocation request, you might have to grant this permission using a [resource-based policy](access-control-resource-based.md). If the principal making the request is in the same AWS account as the function URL, then the principal must **either** have `lambda:InvokeFunctionUrl` and `lambda:InvokeFunction` permissions in their [identity-based policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_identity-vs-resource.html), **or** have permissions granted to them in the function's resource-based policy. In other words, a resource-based policy is optional if the user already has `lambda:InvokeFunctionUrl` and `lambda:InvokeFunction` permissions in their identity-based policy. Policy evaluation follows the rules outlined in [Policy evaluation logic](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html). If the principal making the request is in a different account, then the principal must have **both** an identity-based policy that gives them `lambda:InvokeFunctionUrl` and `lambda:InvokeFunction` permissions **and** permissions granted to them in a resource-based policy on the function that they are trying to invoke. Policy evaluation follows the rules outlined in [Determining whether a cross-account request is allowed](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic-cross-account.html#policy-eval-cross-account). The following resource-based policy allows the `example` role in AWS account `444455556666` to invoke the function URL associated with function `my-function`. The [lambda:InvokedViaFunctionUrl](https://docs.aws.amazon.com/lambda/latest/api/API_AddPermission.html#lambda-AddPermission-request-InvokedViaFunctionUrl) context key restricts the `lambda:InvokeFunction` action to function URL calls. This means that the principal must use the function URL to invoke the function. If you don't include `lambda:InvokedViaFunctionUrl`, the principal can invoke your function through other invocation methods, in addition to the function URL. **Example — Cross-account resource-based policy** **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::444455556666:role/example" }, "Action": "lambda:InvokeFunctionUrl", "Resource": "arn:aws:lambda:us-east-1:123456789012:function:my-function", "Condition": { "StringEquals": { "lambda:FunctionUrlAuthType": "AWS_IAM" } } }, { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::444455556666:role/example" }, "Action": "lambda:InvokeFunction", "Resource": "arn:aws:lambda:us-east-1:123456789012:function:my-function", "Condition": { "Bool": { "lambda:InvokedViaFunctionUrl": "true" } } } ] } ``` You can create this resource-based policy through the console using the following steps: **To grant URL invocation permissions to another account (console)** 1. Open the [Functions page](https://console.aws.amazon.com/lambda/home#/functions) of the Lambda console. 1. Choose the name of the function that you want to grant URL invocation permissions for. 1. Choose the **Configuration** tab, and then choose **Permissions**. 1. Under **Resource-based policy**, choose **Add permissions**. 1. Choose **Function URL**. 1. For **Auth type**, choose **AWS\$1IAM**. 1. Enter a **Statement ID** for your policy statement. 1. For **Principal**, enter the account ID or the Amazon Resource Name (ARN) of the user or role that you want to grant permissions to. For example: **444455556666**. 1. Choose **Save**. Alternatively, you can create this policy using the following [add-permission](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/add-permission.html) AWS Command Line Interface (AWS CLI) commands. When you use the AWS CLI, you must add the `lambda:InvokeFunctionUrl` and `lambda:InvokeFunction` statements separately. For example: ``` aws lambda add-permission --function-name my-function \ --statement-id UrlPolicyInvokeURL \ --action lambda:InvokeFunctionUrl \ --principal 444455556666 \ --function-url-auth-type AWS_IAM ``` ``` aws lambda add-permission --function-name my-function \ --statement-id UrlPolicyInvokeFunction \ --action lambda:InvokeFunction \ --principal 444455556666 \ --invoked-via-function-url ``` ## Using the `NONE` auth type **Important** When your function URL auth type is `NONE` and you have a [resource-based policy](access-control-resource-based.md) that grants public access, any unauthenticated user with your function URL can invoke your function. In some cases, you might want your function URL to be public. For example, you might want to serve requests made directly from a web browser. To allow public access to your function URL, choose the `NONE` auth type. If you choose the `NONE` auth type, Lambda doesn't use IAM to authenticate requests to your function URL. However, your function must have a resource-based policy that allows `lambda:InvokeFunctionUrl` and `lambda:InvokeFunction`. When you create a function URL with auth type `NONE` using the console or AWS Serverless Application Model (AWS SAM), Lambda automatically creates the resource-based policy for you. If you're using the AWS CLI, AWS CloudFormation, or the Lambda API directly, you must [add the policy yourself](#policy-cli). We recommend that you include the [lambda:InvokedViaFunctionUrl](https://docs.aws.amazon.com/lambda/latest/api/API_AddPermission.html#lambda-AddPermission-request-InvokedViaFunctionUrl) context key in your resource-based policies when using the `NONE` auth type. This context key ensures that the function can only be invoked through the function URL and not through other invocation methods. Note the following about this policy: + All entities can call `lambda:InvokeFunctionUrl` and `lambda:InvokeFunction`. This means that anyone who has your function URL can invoke your function. + The `lambda:FunctionUrlAuthType` condition key value is `NONE`. This means that the policy statement allows access only when your function URL's auth type is also `NONE`. + The `lambda:InvokedViaFunctionUrl` condition ensures that the function can only be invoked through the function URL and not through other invocation methods. **Example — Default resource-based policy for NONE auth type** **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "FunctionURLAllowPublicAccess", "Effect": "Allow", "Principal": "*", "Action": "lambda:InvokeFunctionUrl", "Resource": "arn:aws:lambda:us-east-2:123456789012:function:my-function", "Condition": { "StringEquals": { "lambda:FunctionUrlAuthType": "NONE" } } }, { "Sid": "FunctionURLInvokeAllowPublicAccess", "Effect": "Allow", "Principal": "*", "Action": "lambda:InvokeFunction", "Resource": "arn:aws:lambda:us-east-2:123456789012:function:my-function", "Condition": { "Bool": { "lambda:InvokedViaFunctionUrl": "true" } } } ] } ``` **Create the resource-based policy using the AWS CLI** Unless you use the console or AWS SAM to create a function URL with auth type `NONE`, you must add the resource-based policy yourself. Use the following commands to create statements for the `lambda:InvokeFunctionUrl` and `lambda:InvokeFunction` permissions. Each statement must be added in a separate command. ``` aws lambda add-permission \ --function-name UrlTestFunction \ --statement-id UrlPolicyInvokeURL \ --action lambda:InvokeFunctionUrl \ --principal * \ --function-url-auth-type NONE ``` ``` aws lambda add-permission \ --function-name UrlTestFunction \ --statement-id UrlPolicyInvokeFunction \ --action lambda:InvokeFunction \ --principal * \ --invoked-via-function-url ``` **Note** If you delete a function URL with auth type `NONE`, Lambda doesn't automatically delete the associated resource-based policy. If you want to delete this policy, you must manually do so. If a function's resource-based policy doesn't grant `lambda:invokeFunctionUrl` and `lambda:InvokeFunction` permissions, users will get a 403 Forbidden error code when they try to invoke your function URL. This will occur even if the function URL uses the `NONE` auth type. ## Governance and access control In addition to function URL invocation permissions, you can also control access on actions used to configure function URLs. Lambda supports the following IAM policy actions for function URLs: + `lambda:InvokeFunctionUrl` – Invoke a Lambda function using the function URL. + `lambda:CreateFunctionUrlConfig` – Create a function URL and set its `AuthType`. + `lambda:UpdateFunctionUrlConfig` – Update a function URL configuration and its `AuthType`. + `lambda:GetFunctionUrlConfig` – View the details of a function URL. + `lambda:ListFunctionUrlConfigs` – List function URL configurations. + `lambda:DeleteFunctionUrlConfig` – Delete a function URL. To allow or deny function URL access to other AWS entities, include these actions in IAM policies. For example, the following policy grants the `example` role in AWS account `444455556666` permissions to update the function URL for function **my-function** in account `123456789012`. **Example cross-account function URL policy** **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::444455556666:role/example" }, "Action": "lambda:UpdateFunctionUrlConfig", "Resource": "arn:aws:lambda:us-east-2:123456789012:function:my-function" } ] } ``` ### Condition keys For fine-grained access control over your function URLs, use condition context keys. Lambda supports the following context keys for function URLs: + `lambda:FunctionUrlAuthType` – Defines an enum value describing the auth type that your function URL uses. The value can be either `AWS_IAM` or `NONE`. + `lambda:InvokedViaFunctionUrl` – Restricts the `lambda:InvokeFunction` action to calls made through the function URL. This ensures that the function can only be invoked using the function URL and not through other invocation methods. For examples of resource-based policies that use the `lambda:InvokedViaFunctionUrl` context key, see the examples in [Using the `AWS_IAM` auth type](#urls-auth-iam) and [Using the `NONE` auth type](#urls-auth-none). You can use these context keys in policies associated with your function. For example, you might want to restrict who can make configuration changes to your function URLs. To deny all `UpdateFunctionUrlConfig` requests to any function with URL auth type `NONE`, you can define the following policy: **Example function URL policy with explicit deny** **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Deny", "Principal": "*", "Action":[ "lambda:UpdateFunctionUrlConfig" ], "Resource": "arn:aws:lambda:us-east-1:123456789012:function:*", "Condition": { "StringEquals": { "lambda:FunctionUrlAuthType": "NONE" } } } ] } ``` To grant the `example` role in AWS account `444455556666` permissions to make `CreateFunctionUrlConfig` and `UpdateFunctionUrlConfig` requests on functions with URL auth type `AWS_IAM`, you can define the following policy: **Example function URL policy with explicit allow** **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::444455556666:role/example" }, "Action":[ "lambda:CreateFunctionUrlConfig", "lambda:UpdateFunctionUrlConfig" ], "Resource": "arn:aws:lambda:us-east-1:123456789012:function:*", "Condition": { "StringEquals": { "lambda:FunctionUrlAuthType": "AWS_IAM" } } } ] } ``` You can also use this condition key in a [service control policy](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps.html) (SCP). Use SCPs to manage permissions across an entire organization in AWS Organizations. For example, to deny users from creating or updating function URLs that use anything other than the `AWS_IAM` auth type, use the following service control policy: **Example function URL SCP with explicit deny** **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Deny", "Action":[ "lambda:CreateFunctionUrlConfig", "lambda:UpdateFunctionUrlConfig" ], "Resource": "arn:aws:lambda:*:123456789012:function:*", "Condition": { "StringNotEquals": { "lambda:FunctionUrlAuthType": "AWS_IAM" } } } ] } ``` # 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. **Tip** Lambda offers two ways to invoke your function through an HTTP endpoint: function URLs and Amazon API Gateway. If you're not sure which is the best method for your use case, see [Select a method to invoke your Lambda function using an HTTP request](furls-http-invoke-decision.md). 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://.lambda-url..on.aws ``` **Note** Function URLs are not supported in the following AWS Regions: Asia Pacific (Hyderabad) (`ap-south-2`), Asia Pacific (Melbourne) (`ap-southeast-4`), Asia Pacific (Malaysia) (`ap-southeast-5`), Asia Pacific (New Zealand) (`ap-southeast-6`), Asia Pacific (Thailand) (`ap-southeast-7`), Asia Pacific (Taipei) (`ap-east-2`), 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` and `lambda:InvokeFunction` permissions. For more information, see [Access control](urls-auth.md). **Topics** + [ ## Function URL invocation basics ](#urls-invocation-basics) + [ ## Request and response payloads ](#urls-payloads) ## 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)](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html). Tools such as [Postman](https://quickstarts.postman.com/guide/aws/index.html?index=..%2F..index#2) 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](https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html) 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](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html#http-api-develop-integrations-lambda.proxy-format). ### Request payload format A request payload has the following structure: ``` { "version": "2.0", "routeKey": "$default", "rawPath": "/my/path", "rawQueryString": "parameter1=value1¶meter1=value2¶meter2=value", "cookies": [ "cookie1", "cookie2" ], "headers": { "header1": "value1", "header2": "value1,value2" }, "queryStringParameters": { "parameter1": "value1,value2", "parameter2": "value" }, "requestContext": { "accountId": "123456789012", "apiId": "", "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": ".lambda-url.us-west-2.on.aws", "domainPrefix": "", "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](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html#http-api-develop-integrations-lambda.proxy-format). | `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¶meter2=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 AWS Identity and Access Management (IAM). | | | `requestContext.accountId` | The AWS 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 AWS 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. | `".lambda-url.us-west-2.on.aws"` | | `requestContext.domainPrefix` | The domain prefix of the function URL. | `""` | | `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`. **Note** The valid `statusCode` are within the range of 100 to 599. + `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!"
}
| # Monitoring Lambda function URLs You can use AWS CloudTrail and Amazon CloudWatch to monitor your function URLs. **Topics** + [ ## Monitoring function URLs with CloudTrail ](#urls-cloudtrail) + [ ## CloudWatch metrics for function URLs ](#urls-cloudwatch) ## Monitoring function URLs with CloudTrail For function URLs, Lambda automatically supports logging the following API operations as events in CloudTrail log files: + [CreateFunctionUrlConfig](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunctionUrlConfig.html) + [UpdateFunctionUrlConfig](https://docs.aws.amazon.com/lambda/latest/api/API_UpdateFunctionUrlConfig.html) + [DeleteFunctionUrlConfig](https://docs.aws.amazon.com/lambda/latest/api/API_DeleteFunctionUrlConfig.html) + [GetFunctionUrlConfig](https://docs.aws.amazon.com/lambda/latest/api/API_GetFunctionUrlConfig.html) + [ListFunctionUrlConfigs](https://docs.aws.amazon.com/lambda/latest/api/API_ListFunctionUrlConfigs.html) Each log entry contains information about the caller identity, when the request was made, and other details. You can see all events within the last 90 days by viewing your CloudTrail **Event history**. To retain records past 90 days, you can create a trail. By default, CloudTrail doesn't log `InvokeFunctionUrl` requests, which are considered data events. However, you can turn on data event logging in CloudTrail. For more information, see [Logging data events for trails](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html) in the *AWS CloudTrail User Guide*. ## CloudWatch metrics for function URLs Lambda sends aggregated metrics about function URL requests to CloudWatch. With these metrics, you can monitor your function URLs, build dashboards, and configure alarms in the CloudWatch console. Function URLs support the following invocation metrics. We recommend viewing these metrics with the `Sum` statistic. + `UrlRequestCount` – The number of requests made to this function URL. + `Url4xxCount` – The number of requests that returned a 4XX HTTP status code. 4XX series codes indicate client-side errors, such as bad requests. + `Url5xxCount` – The number of requests that returned a 5XX HTTP status code. 5XX series codes indicate server-side errors, such as function errors and timeouts. Function URLs also support the following performance metric. We recommend viewing this metric with the `Average` or `Max` statistics. + `UrlRequestLatency` – The time between when the function URL receives a request and when the function URL returns a response. Each of these invocation and performance metrics supports the following dimensions: + `FunctionName` – View aggregate metrics for function URLs assigned to a function's `$LATEST` unpublished version, or to any of the function's aliases. For example, `hello-world-function`. + `Resource` – View metrics for a specific function URL. This is defined by a function name, along with either the function's `$LATEST` unpublished version or one of the function's aliases. For example, `hello-world-function:$LATEST`. + `ExecutedVersion` – View metrics for a specific function URL based on the executed version. You can use this dimension primarily to track the function URL assigned to the `$LATEST` unpublished version. # Select a method to invoke your Lambda function using an HTTP request Many common use cases for Lambda involve invoking your function using an HTTP request. For example, you might want a web application to invoke your function through a browser request. Lambda functions can also be used to create full REST APIs, handle user interactions from mobile apps, process data from external services via HTTP calls, or create custom webhooks. The following sections explain what your choices are for invoking Lambda through HTTP and provide information to help you make the right decision for your particular use case. ## What are your choices when selecting an HTTP invoke method? Lambda offers two main methods to invoke a function using an HTTP request - [function URLs](urls-configuration.md) and [API Gateway](services-apigateway.md). The key differences between these two options are as follows: + **Lambda function URLs** provide a simple, direct HTTP endpoint for a Lambda function. They are optimized for simplicity and cost-effectiveness and provide the fastest path to expose a Lambda function via HTTP. + **API Gateway** is a more advanced service for building fully-featured APIs. API Gateway is optimized for building and managing productions APIs at scale and provides comprehensive tools for security, monitoring, and traffic management. ## Recommendations if you already know your requirements If you're already clear on your requirements, here are our basic recommendations: We recommend **[function URLs](urls-configuration.md)** for simple applications or prototyping where you only need basic authentication methods and request/response handling and where you want to keep costs and complexity to a minimum. **[API Gateway](services-apigateway.md)** is a better choice for production applications at scale or for cases where you need more advanced features like [OpenAPI Description](https://www.openapis.org/) support, a choice of authentication options, custom domain names, or rich request/response handling including throttling, caching, and request/response transformation. ## What to consider when selecting a method to invoke your Lambda function When selecting between function URLs and API Gateway, you need to consider the following factors: + Your authentication needs, such as whether you require OAuth or Amazon Cognito to authenticate users + Your scaling requirements and the complexity of the API you want to implement + Whether you need advanced features such as request validation and request/response formatting + Your monitoring requirements + Your cost goals By understanding these factors, you can select the option that best balances your security, complexity, and cost requirements. The following information summarizes the main differences between the two options. ### Authentication + **Function URLs** provide basic authentication options through AWS Identity and Access Management (IAM). You can configure your endpoints to be either public (no authentication) or to require IAM authentication. With IAM authentication, you can use standard AWS credentials or IAM roles to control access. While straightforward to set up, this approach provides limited options compared with other authenticaton methods. + **API Gateway** provides access to a more comprehensive range of authentication options. As well as IAM authentication, you can use [Lambda authorizers](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html) (custom authentication logic), [Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/what-is-amazon-cognito.html) user pools, and OAuth2.0 flows. This flexibility allows you to implement complex authentication schemes, including third-party authentication providers, token-based authentication, and multi-factor authentication. ### Request/response handling + **Function URLs** provide basic HTTP request and response handling. They support standard HTTP methods and include built-in cross-origin resource sharing (CORS) support. While they can handle JSON payloads and query parameters naturally, they don't offer request transformation or validation capabilities. Response handling is similarly straightforward – the client receives the response from your Lambda function exactly as Lambda returns it. + **API Gateway** provides sophisticated request and response handling capabilities. You can define request validators, transform requests and responses using mapping templates, set up request/response headers, and implement response caching. API Gateway also supports binary payloads and custom domain names and can modify responses before they reach the client. You can set up models for request/response validation and transformation using JSON Schema. ### Scaling + **Function URLs** scale directly with your Lambda function's concurrency limits and handle traffic spikes by scaling your function up to its maximum configured concurrency limit. Once that limit is reached, Lambda responds to additional requests with HTTP 429 responses. There's no built-in queuing mechanism, so handling scaling is entirely dependent on your Lambda function's configuration. By default, Lambda functions have a limit of 1,000 concurrent executions per AWS Region. + **API Gateway** provides additional scaling capabilities on top of Lambda's own scaling. It includes built-in request queuing and throttling controls, allowing you to manage traffic spikes more gracefully. API Gateway can handle up to 10,000 requests per second per region by default, with a burst capacity of 5,000 requests per second. It also provides tools to throttle requests at different levels (API, stage, or method) to protect your backend. ### Monitoring + **Function URLs** offer basic monitoring through Amazon CloudWatch metrics, including request count, latency, and error rates. You get access to standard Lambda metrics and logs, which show the raw requests coming into your function. While this provides essential operational visibility, the metrics are focused mainly on function execution. + **API Gateway** provides comprehensive monitoring capabilities including detailed metrics, logging, and tracing options. You can monitor API calls, latency, error rates, and cache hit/miss rates through CloudWatch. API Gateway also integrates with AWS X-Ray for distributed tracing and provides customizable logging formats. ### Cost + **Function URLs** follow the standard Lambda pricing model – you only pay for function invocations and compute time. There are no additional charges for the URL endpoint itself. This makes it a cost-effective choice for simple APIs or low-traffic applications if you don't need the additional features of API Gateway. + **API Gateway** offers a [free tier](https://aws.amazon.com/api-gateway/pricing/#Free_Tier) that includes one million API calls received for REST APIs and one million API calls received for HTTP APIs. After this, API Gateway charges for API calls, data transfer, and caching (if enabled). Refer to the API Gateway [pricing page](https://aws.amazon.com/api-gateway/pricing/) to understand the costs for your own use case. ### Other features + **Function URLs** are designed for simplicity and direct Lambda integration. They support both HTTP and HTTPS endpoints, offer built-in CORS support, and provide dual-stack (IPv4 and IPv6) endpoints. While they lack advanced features, they excel in scenarios where you need a quick, straightforward way to expose Lambda functions via HTTP. + **API Gateway** includes numerous additional features such as API versioning, stage management, API keys for usage plans, API documentation through Swagger/OpenAPI, WebSocket APIs, private APIs within a VPC, and WAF integration for additional security. It also supports canary deployments, mock integrations for testing, and integration with other AWS services beyond Lambda. ## Select a method to invoke your Lambda function Now that you've read about the criteria for selecting between Lambda function URLs and API Gateway and the key differences between them, you can select the option that best meets your needs and use the following resources to help you get started using it. ------ #### [ Function URLs ] **Get started with function URLs with the following resources** + Follow the tutorial [Creating a Lambda function with a function URL](urls-webhook-tutorial.md) + Learn more about function URLs in the [Creating and managing Lambda function URLs](urls-configuration.md) chapter of this guide + Try the in-console guided tutorial **Create a simple web app** by doing the following: 1. Open the [functions page](https://console.aws.amazon.com/lambda/home#/functions) of the Lambda console. 1. Open the help panel by choosing the icon in the top right corner of the screen. ![\[\]](http://docs.aws.amazon.com/lambda/latest/dg/images/console_help_screenshot.png) 1. Select **Tutorials**. 1. In **Create a simple web app**, choose **Start tutorial**. ------ #### [ API Gateway ] **Get started with Lambda and API Gateway with the following resources** + Follow the tutorial [Using Lambda with API Gateway](services-apigateway-tutorial.md) to create a REST API integrated with a backend Lambda function. + Learn more about the different kinds of API offered by API Gateway in the following sections of the *Amazon API Gateway Developer Guide*: + [API Gateway REST APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-rest-api.html) + [API Gateway HTTP APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api.html) + [API Gateway WebSocket APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api.html) + Try one or more of the examples in the [Tutorials and workshops](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-tutorials.html) section of the *Amazon API Gateway Developer Guide*. ------ # Tutorial: Creating a webhook endpoint using a Lambda function URL In this tutorial, you create a Lambda function URL to implement a webhook endpoint. A webhook is a lightweight, event-driven communication that automatically sends data between applications using HTTP. You can use a webhook to receive immediate updates about events happening in another system, such as when a new customer signs up on a website, a payment is processed, or a file is uploaded. With Lambda, webhooks can be implemented using either Lambda function URLs or API Gateway. Function URLs are a good choice for simple webhooks that don't require features like advanced authorization or request validation. **Tip** If you're not sure which solution is best for your particular use case, see [Select a method to invoke your Lambda function using an HTTP request](furls-http-invoke-decision.md). ## Prerequisites To complete this tutorial, you must have either Python (version 3.8 or later) or Node.js (version 18 or later) installed on your local machine. To test the endpoint using an HTTP request, the tutorial uses [curl](https://curl.se/), a command line tool you can use to transfer data using various network protocols. Refer to the [curl documentation](https://curl.se/docs/install.html) to learn how to install the tool if you don't already have it. ## Create the Lambda function First create the Lambda function that runs when an HTTP request is sent to your webhook endpoint. In this example, the sending application sends an update whenever a payment is submitted and indicates in the body of the HTTP request whether the payment was successful. The Lambda function parses the request and takes action according to the status of the payment. In this example, the code just prints the order ID for the payment, but in a real application, you might add the order to a database or send a notification. The function also implements the most common authentication method used for webhooks, hash-based message authentication (HMAC). With this method, both the sending and receiving applications share a secret key. The sending application uses a hashing algorithm to generate a unique signature using this key together with the message content, and includes the signature in the webhook request as an HTTP header. The receiving application then repeats this step, generating the signature using the secret key, and compares the resulting value with the signature sent in the request header. If the result matches, the request is considered legitimate. Create the function using the Lambda console with either the Python or Node.js runtime. ------ #### [ Python ] **Create the Lambda function** 1. Open the [Functions page](https://console.aws.amazon.com/lambda/home#/functions) of the Lambda console. 1. Create a basic 'Hello world' function by doing the following: 1. Choose **Create function**. 1. Select **Author from scratch**. 1. For **Function name**, enter **myLambdaWebhook**. 1. For **Runtime**, select **python3.14**. 1. Choose **Create function**. 1. In the **Code source** pane, replace the existing code by copying and pasting the following: ``` import json import hmac import hashlib import os def lambda_handler(event, context): # Get the webhook secret from environment variables webhook_secret = os.environ['WEBHOOK_SECRET'] # Verify the webhook signature if not verify_signature(event, webhook_secret): return { 'statusCode': 401, 'body': json.dumps({'error': 'Invalid signature'}) } try: # Parse the webhook payload payload = json.loads(event['body']) # Handle different event types event_type = payload.get('type') if event_type == 'payment.success': # Handle successful payment order_id = payload.get('orderId') print(f"Processing successful payment for order {order_id}") # Add your business logic here # For example, update database, send notifications, etc. elif event_type == 'payment.failed': # Handle failed payment order_id = payload.get('orderId') print(f"Processing failed payment for order {order_id}") # Add your business logic here else: print(f"Received unhandled event type: {event_type}") # Return success response return { 'statusCode': 200, 'body': json.dumps({'received': True}) } except json.JSONDecodeError: return { 'statusCode': 400, 'body': json.dumps({'error': 'Invalid JSON payload'}) } except Exception as e: print(f"Error processing webhook: {e}") return { 'statusCode': 500, 'body': json.dumps({'error': 'Internal server error'}) } def verify_signature(event, webhook_secret): """ Verify the webhook signature using HMAC """ try: # Get the signature from headers signature = event['headers'].get('x-webhook-signature') if not signature: print("Error: Missing webhook signature in headers") return False # Get the raw body (return an empty string if the body key doesn't exist) body = event.get('body', '') # Create HMAC using the secret key expected_signature = hmac.new( webhook_secret.encode('utf-8'), body.encode('utf-8'), hashlib.sha256 ).hexdigest() # Compare the expected signature with the received signature to authenticate the message is_valid = hmac.compare_digest(signature, expected_signature) if not is_valid: print(f"Error: Invalid signature. Received: {signature}, Expected: {expected_signature}") return False return True except Exception as e: print(f"Error verifying signature: {e}") return False ``` 1. In the **DEPLOY** section, choose **Deploy** to update your function's code. ------ #### [ Node.js ] **Create the Lambda function** 1. Open the [Functions page](https://console.aws.amazon.com/lambda/home#/functions) of the Lambda console. 1. Create a basic 'Hello world' function by doing the following: 1. Choose **Create function**. 1. Select **Author from scratch**. 1. For **Function name**, enter **myLambdaWebhook**. 1. For **Runtime**, select **nodejs24.x**. 1. Choose **Create function**. 1. In the **Code source** pane, replace the existing code by copying and pasting the following: ``` import crypto from 'crypto'; export const handler = async (event, context) => { // Get the webhook secret from environment variables const webhookSecret = process.env.WEBHOOK_SECRET; // Verify the webhook signature if (!verifySignature(event, webhookSecret)) { return { statusCode: 401, body: JSON.stringify({ error: 'Invalid signature' }) }; } try { // Parse the webhook payload const payload = JSON.parse(event.body); // Handle different event types const eventType = payload.type; switch (eventType) { case 'payment.success': { // Handle successful payment const orderId = payload.orderId; console.log(`Processing successful payment for order ${orderId}`); // Add your business logic here // For example, update database, send notifications, etc. break; } case 'payment.failed': { // Handle failed payment const orderId = payload.orderId; console.log(`Processing failed payment for order ${orderId}`); // Add your business logic here break; } default: console.log(`Received unhandled event type: ${eventType}`); } // Return success response return { statusCode: 200, body: JSON.stringify({ received: true }) }; } catch (error) { if (error instanceof SyntaxError) { // Handle JSON parsing errors return { statusCode: 400, body: JSON.stringify({ error: 'Invalid JSON payload' }) }; } // Handle all other errors console.error('Error processing webhook:', error); return { statusCode: 500, body: JSON.stringify({ error: 'Internal server error' }) }; } }; // Verify the webhook signature using HMAC const verifySignature = (event, webhookSecret) => { try { // Get the signature from headers const signature = event.headers['x-webhook-signature']; if (!signature) { console.log('No signature found in headers:', event.headers); return false; } // Get the raw body (return an empty string if the body key doesn't exist) const body = event.body || ''; // Create HMAC using the secret key const hmac = crypto.createHmac('sha256', webhookSecret); const expectedSignature = hmac.update(body).digest('hex'); // Compare expected and received signatures const isValid = signature === expectedSignature; if (!isValid) { console.log(`Invalid signature. Received: ${signature}, Expected: ${expectedSignature}`); return false; } return true; } catch (error) { console.error('Error during signature verification:', error); return false; } }; ``` 1. In the **DEPLOY** section, choose **Deploy** to update your function's code. ------ ## Create the secret key For the Lambda function to authenticate the webhook request, it uses a secret key which it shares with the calling application. In this example, the key is stored in an environment variable. In a production application, don't include sensitive information like passwords in your function code. Instead, [create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html) and then [use the AWS Parameters and Secrets Lambda extension](with-secrets-manager.md) to retrieve your credentials in your Lambda function. **Create and store the webhook secret key** 1. Generate a long, random string using a cryptographically secure random number generator. You can use the following code snippets in Python or Node.js to generate and print a 32-character secret, or use your own preferred method. ------ #### [ Python ] **Example code to generate a secret** ``` import secrets webhook_secret = secrets.token_urlsafe(32) print(webhook_secret) ``` ------ #### [ Node.js ] **Example code to generate a secret (ES module format)** ``` import crypto from 'crypto'; let webhookSecret = crypto.randomBytes(32).toString('base64'); console.log(webhookSecret) ``` ------ 1. Store your generated string as an environment variable for your function by doing the following: 1. In the **Configuration** tab for your function, select **Environment variables**. 1. Choose **Edit**. 1. Choose **Add environment variable**. 1. For **Key**, enter **WEBHOOK\$1SECRET**, then for **Value**, enter the secret you generated in the previous step. 1. Choose **Save**. You'll need to use this secret again later in the tutorial to test your function, so make a note of it now. ## Create the function URL endpoint Create an endpoint for your webhook using a Lambda function URL. Beacuse you use the auth type of `NONE` to create an endpoint with public access, anyone with the URL can invoke your function. To learn more about controlling access to function URLs, see [Control access to Lambda function URLs](urls-auth.md). If you need more advanced authentication options for your webhook, consider using API Gateway. **Create the function URL endpoint** 1. In the **Configuration** tab for your function, select **Function URL**. 1. Choose **Create function URL**. 1. For **Auth type**, select **NONE**. 1. Choose **Save**. The endpoint for the function URL you just created is displayed in the **Function URL** pane. Copy the endpoint to use later in the tutorial. ## Test the function in the console Before using an HTTP request to invoke your function using the URL endpoint, test it in the console to confirm your code is working as expected. To verify the function in the console, you first calculate a webhook signature using the secret you generated earlier in the tutorial with the following test JSON payload: ``` { "type": "payment.success", "orderId": "1234", "amount": "99.99" } ``` Use either of the following Python or Node.js code examples to calculate the webhook signature using your own secret. ------ #### [ Python ] **Calculate the webhook signature** 1. Save the following code as a file named `calculate_signature.py`. Replace the webhook secret in the code with your own value. ``` import secrets import hmac import json import hashlib webhook_secret = "arlbSDCP86n_1H90s0fL_Qb2NAHBIBQOyGI0X4Zay4M" body = json.dumps({"type": "payment.success", "orderId": "1234", "amount": "99.99"}) signature = hmac.new( webhook_secret.encode('utf-8'), body.encode('utf-8'), hashlib.sha256 ).hexdigest() print(signature) ``` 1. Calculate the signature by running the following command from the same directory you saved the code in. Copy the signature the code outputs. ``` python calculate_signature.py ``` ------ #### [ Node.js ] **Calculate the webhook signature** 1. Save the following code as a file named `calculate_signature.mjs`. Replace the webhook secret in the code with your own value. ``` import crypto from 'crypto'; const webhookSecret = "arlbSDCP86n_1H90s0fL_Qb2NAHBIBQOyGI0X4Zay4M" const body = "{\"type\": \"payment.success\", \"orderId\": \"1234\", \"amount\": \"99.99\"}"; let hmac = crypto.createHmac('sha256', webhookSecret); let signature = hmac.update(body).digest('hex'); console.log(signature); ``` 1. Calculate the signature by running the following command from the same directory you saved the code in. Copy the signature the code outputs. ``` node calculate_signature.mjs ``` ------ You can now test your function code using a test HTTP request in the console. **Test the function in the console** 1. Select the **Code** tab for your function. 1. In the **TEST EVENTS** section, choose **Create new test event** 1. For **Event Name**, enter **myEvent**. 1. Replace the existing JSON by copying and pasting the following into the **Event JSON** pane. Replace the webhook signature with the value you calculated in the previous step. ``` { "headers": { "Content-Type": "application/json", "x-webhook-signature": "2d672e7a0423fab740fbc040e801d1241f2df32d2ffd8989617a599486553e2a" }, "body": "{\"type\": \"payment.success\", \"orderId\": \"1234\", \"amount\": \"99.99\"}" } ``` 1. Choose **Save**. 1. Choose **Invoke**. You should see output similar to the following: ------ #### [ Python ] ``` Status: Succeeded Test Event Name: myEvent Response: { "statusCode": 200, "body": "{\"received\": true}" } Function Logs: START RequestId: 50cc0788-d70e-453a-9a22-ceaa210e8ac6 Version: $LATEST Processing successful payment for order 1234 END RequestId: 50cc0788-d70e-453a-9a22-ceaa210e8ac6 REPORT RequestId: 50cc0788-d70e-453a-9a22-ceaa210e8ac6 Duration: 1.55 ms Billed Duration: 2 ms Memory Size: 128 MB Max Memory Used: 36 MB Init Duration: 136.32 ms ``` ------ #### [ Node.js ] ``` Status: Succeeded Test Event Name: myEvent Response: { "statusCode": 200, "body": "{\"received\":true}" } Function Logs: START RequestId: e54fe6c7-1df9-4f05-a4c4-0f71cacd64f4 Version: $LATEST 2025-01-10T18:05:42.062Z e54fe6c7-1df9-4f05-a4c4-0f71cacd64f4 INFO Processing successful payment for order 1234 END RequestId: e54fe6c7-1df9-4f05-a4c4-0f71cacd64f4 REPORT RequestId: e54fe6c7-1df9-4f05-a4c4-0f71cacd64f4 Duration: 60.10 ms Billed Duration: 61 ms Memory Size: 128 MB Max Memory Used: 72 MB Init Duration: 174.46 ms Request ID: e54fe6c7-1df9-4f05-a4c4-0f71cacd64f4 ``` ------ ## Test the function using an HTTP request Use the curl command line tool to test your webhook endpoint. **Test the function using HTTP requests** 1. In a terminal or shell program, run the following curl command. Replace the URL with the value for your own function URL endpoint and replace the webhook signature with the signature you calculated using your own secret key. ``` curl -X POST https://ryqgmbx5xjzxahif6frvzikpre0bpvpf.lambda-url.us-west-2.on.aws/ \ -H "Content-Type: application/json" \ -H "x-webhook-signature: d5f52b76ffba65ff60ea73da67bdf1fc5825d4db56b5d3ffa0b64b7cb85ef48b" \ -d '{"type": "payment.success", "orderId": "1234", "amount": "99.99"}' ``` You should see the following output: ``` {"received": true} ``` 1. Inspect the CloudWatch logs for your function to confirm it parsed the payload correctly by doing the following: 1. Open the [Logs group](https://console.aws.amazon.com/cloudwatch/home#logsV2:log-groups) page in the Amazon CloudWatch console. 1. Select your function's log group (`/aws/lambda/myLambdaWebhook`). 1. Select the most recent log stream. You should see output similar to the following in your function's logs: ------ #### [ Python ] ``` Processing successful payment for order 1234 ``` ------ #### [ Node.js ] ``` 2025-01-10T18:05:42.062Z e54fe6c7-1df9-4f05-a4c4-0f71cacd64f4 INFO Processing successful payment for order 1234 ``` ------ 1. Confirm that your code detects an invalid signature by running the following curl command. Replace the URL with your own function URL endpoint. ``` curl -X POST https://ryqgmbx5xjzxahif6frvzikpre0bpvpf.lambda-url.us-west-2.on.aws/ \ -H "Content-Type: application/json" \ -H "x-webhook-signature: abcdefg" \ -d '{"type": "payment.success", "orderId": "1234", "amount": "99.99"}' ``` You should see the following output: ``` {"error": "Invalid signature"} ``` ## Clean up your resources You can now delete the resources that you created for this tutorial, unless you want to retain them. By deleting AWS resources that you're no longer using, you prevent unnecessary charges to your AWS account. **To delete the Lambda function** 1. Open the [Functions page](https://console.aws.amazon.com/lambda/home#/functions) of the Lambda console. 1. Select the function that you created. 1. Choose **Actions**, **Delete**. 1. Type **confirm** in the text input field and choose **Delete**. When you created the Lambda function in the console, Lambda also created an [execution role](lambda-intro-execution-role.md) for your function. **To delete the execution role** 1. Open the [Roles page](https://console.aws.amazon.com/iam/home#/roles) of the IAM console. 1. Select the execution role that Lambda created. The role has the name format `myLambdaWebhook-role-`. 1. Choose **Delete**. 1. Enter the name of the role in the text input field and choose **Delete**.