# How to Receive and Replay External Webhooks in AWS Lambda with Hookdeck

Webhooks play a crucial role in facilitating seamless, real-time communication between different services in modern application development. [AWS Lambda](https://aws.amazon.com/lambda/) allows you to host and manage webhook endpoints without the hassle of maintaining servers.

[Hookdeck Event Gateway](https://hookdeck.com/) is a reliable event gateway for managing inbound events, including monitoring and replaying webhooks. Hookdeck supports [AWS destination authentication](/docs/authentication), enabling it to invoke AWS Lambda functions directly via [Lambda Function URLs](https://docs.aws.amazon.com/lambda/latest/dg/lambda-urls.html) with `AWS_IAM` auth.

This guide covers:

1. Creating an AWS Lambda function with a Function URL using the AWS CLI
2. Configuring a Hookdeck connection with AWS authentication to route webhooks to your Lambda function
3. Receiving, monitoring, and replaying webhook events

## Prerequisites

Before you begin, ensure you have the following:

* AWS CLI installed and configured with appropriate credentials. See the [AWS CLI installation guide](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
* Hookdeck CLI installed. See the [Hookdeck CLI docs](/docs/cli).
* An AWS account with permissions to create Lambda functions and IAM roles.
* A Hookdeck account. [Sign up for free](https://dashboard.hookdeck.com/signup) if you don't have one.

## Create an AWS Lambda function

First, create an IAM execution role for your Lambda function. This role allows Lambda to write logs to CloudWatch:

```bash
aws iam create-role \
  --role-name webhookHandlerRole \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": {"Service": "lambda.amazonaws.com"},
      "Action": "sts:AssumeRole"
    }]
  }'

```

Attach the basic execution policy so the function can write logs:

```bash
aws iam attach-role-policy \
  --role-name webhookHandlerRole \
  --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole

```

Next, create the Lambda function code. Create a file called `index.mjs`:

```javascript
export const handler = async (event) => {
  try {
    const body = JSON.parse(event.body || "{}");

    console.log("Webhook received:", JSON.stringify(body, null, 2));

    return {
      statusCode: 200,
      body: JSON.stringify({ message: "Webhook received!" }),
    };
  } catch (error) {
    console.error("Error processing webhook:", error);

    return {
      statusCode: 400,
      body: JSON.stringify({ message: error.message }),
    };
  }
};

```

Package and deploy the function:

```bash
zip function.zip index.mjs

aws lambda create-function \
  --function-name webhookHandler \
  --runtime nodejs22.x \
  --handler index.handler \
  --zip-file fileb://function.zip \
  --role arn:aws:iam::YOUR_ACCOUNT_ID:role/webhookHandlerRole

```

> Replace `YOUR_ACCOUNT_ID` with your AWS account ID. You can find it by running `aws sts get-caller-identity --query Account --output text`.

## Create a Lambda Function URL

You can expose your Lambda function directly using a [Function URL](https://docs.aws.amazon.com/lambda/latest/dg/lambda-urls.html) with `AWS_IAM` authentication — no API Gateway required. Hookdeck Event Gateway signs requests using AWS Signature V4, so only authenticated requests can invoke your function.

Create the Function URL:

```bash
aws lambda create-function-url-config \
  --function-name webhookHandler \
  --auth-type AWS_IAM

```

This returns a `FunctionUrl` value (e.g., `https://<url-id>.lambda-url.<region>.on.aws/`). Save this URL — you'll need it when configuring Hookdeck.

Next, grant permission for your AWS IAM user (the one Hookdeck will authenticate as) to invoke the function URL. Replace `YOUR_AWS_ACCOUNT_ID` and `YOUR_IAM_USER` with the appropriate values for the IAM credentials you'll provide to Hookdeck:

```bash
aws lambda add-permission \
  --function-name webhookHandler \
  --statement-id hookdeck-invoke \
  --action lambda:InvokeFunctionUrl \
  --principal YOUR_AWS_ACCOUNT_ID \
  --function-url-auth-type AWS_IAM

```

> If you want any authenticated IAM identity in your account to be able to invoke the function, you can set `--principal` to your account ID. For more granular control, specify a specific IAM user or role ARN using `--principal-org-id` or `--source-arn` conditions.

You can verify the Function URL is configured correctly:

```bash
aws lambda get-function-url-config --function-name webhookHandler

```

## Create a Hookdeck connection

Now, create a Hookdeck [connection](/docs/connections) that routes webhook events from a source to your Lambda function, using AWS Signature authentication.

### CLI
Log in to the Hookdeck CLI if you haven't already:
```bash
hookdeck login

```

Create the connection with AWS destination authentication:
```bash
hookdeck connection upsert aws-lambda-webhooks \
  --source-name webhook-source --source-type WEBHOOK \
  --destination-name aws-lambda --destination-type HTTP \
  --destination-url YOUR_LAMBDA_FUNCTION_URL \
  --destination-auth-method aws \
  --destination-aws-access-key-id $AWS_ACCESS_KEY_ID \
  --destination-aws-secret-access-key $AWS_SECRET_ACCESS_KEY \
  --destination-aws-region YOUR_AWS_REGION \
  --destination-aws-service lambda

```

Replace the placeholder values:* `YOUR_LAMBDA_FUNCTION_URL` — the Function URL from the previous step
* `$AWS_ACCESS_KEY_ID` and `$AWS_SECRET_ACCESS_KEY` — IAM credentials with permission to invoke the function
* `YOUR_AWS_REGION` — the AWS region where your Lambda function is deployed (e.g., `us-east-1`)The CLI outputs a Source URL (e.g., `https://hkdk.events/...`). Use this URL as the webhook endpoint in your source platform.

### Dashboard
1. Go to your [Hookdeck Dashboard](https://dashboard.hookdeck.com/) and navigate to Connections.
2. Click the Create button in the top right.
3. Configure the Source:
  
  * Set a name (e.g., `webhook-source`)
4. Configure the Destination:
  
  * Set a name (e.g., `aws-lambda`)
  * Set the URL to your Lambda Function URL
  * Under Authentication, select AWS Signature as the auth method
  * Enter your AWS Access Key ID, Secret Access Key, Region, and set Service to `lambda`
5. Click Create.After creating the connection, copy the Source URL to use as the webhook endpoint in your source platform.

### API

```bash
curl -X POST "https://api.hookdeck.com/2025-07-01/connections" \
  -H "Authorization: Bearer $HOOKDECK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "aws-lambda-webhooks",
    "source": {
      "name": "webhook-source"
    },
    "destination": {
      "name": "aws-lambda",
      "config": {
        "url": "YOUR_LAMBDA_FUNCTION_URL",
        "auth_type": "AWS_SIGNATURE",
        "auth": {
          "access_key_id": "YOUR_AWS_ACCESS_KEY_ID",
          "secret_access_key": "YOUR_AWS_SECRET_ACCESS_KEY",
          "region": "YOUR_AWS_REGION",
          "service": "lambda"
        }
      }
    }
  }'

```

Replace the placeholder values with your Lambda Function URL, AWS credentials, and region.The response includes a `source.url` field — use this as the webhook endpoint in your source platform.

After creating the connection, you are given a Source URL to use on the source platform. The created connection allows webhook events from your source to be relayed directly to your Lambda function through Hookdeck, authenticated using AWS Signature V4.

## Receive and monitor webhook events

Once your connection is configured and the Source URL is registered with your webhook provider, events will flow through Hookdeck to your Lambda function.

You can monitor events in two ways:

### Hookdeck Dashboard

From your [Hookdeck Dashboard](https://dashboard.hookdeck.com/), go to the Events section. Filter by your connection to see all webhook activity, including request and response details.

### AWS CloudWatch Logs

You can also check your Lambda function's logs using the AWS CLI:

```bash
aws logs tail /aws/lambda/webhookHandler --follow

```

This streams the latest log output from your function, including the webhook payloads logged by the handler.

## Retry failed webhooks

If a webhook event fails (e.g., your Lambda function returns an error or times out), Hookdeck makes it easy to [retry the event](/docs/retries).

From the Events section in the Hookdeck Dashboard:

1. Find the failed event (indicated by an error status)
2. Click on the event to view its details
3. Click the Retry button to resend the event to your Lambda function

Hookdeck also supports [automatic retries](/docs/retries) that you can configure on your connection. You can set retry strategies (linear or exponential backoff), retry counts, and which HTTP status codes trigger a retry.

### Dashboard
1. Navigate to your connection in the Hookdeck Dashboard
2. Click Rules and add a Retry rule
3. Configure the retry strategy, interval, count, and status codes

### API

```bash
curl -X PUT "https://api.hookdeck.com/2025-07-01/connections" \
  -H "Authorization: Bearer $HOOKDECK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "aws-lambda-webhooks",
    "source": {
      "name": "webhook-source"
    },
    "destination": {
      "name": "aws-lambda",
      "config": {
        "url": "YOUR_LAMBDA_FUNCTION_URL"
      }
    },
    "rules": [
      {
        "type": "retry",
        "strategy": "linear",
        "interval": 60000,
        "count": 5,
        "response_status_codes": ["500", "502", "503", "504"]
      }
    ]
  }'

```

## Summary

By combining AWS Lambda Function URLs with Hookdeck's AWS destination authentication, you can receive and process webhooks reliably. Hookdeck Event Gateway provides:

* Queueing and rate limiting to protect your Lambda function from traffic spikes
* Observability with detailed logs of every webhook event
* Automatic and manual retries to ensure no event is lost
* Filtering and transformations to route and modify events before they reach your function

To explore more features, check out the [Hookdeck documentation](/docs).