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 allows you to host and manage webhook endpoints without the hassle of maintaining servers.

Hookdeck Event Gateway is a reliable event gateway for managing inbound events, including monitoring and replaying webhooks. Hookdeck supports AWS destination authentication, enabling it to invoke AWS Lambda functions directly via Lambda Function URLs 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.
• Hookdeck CLI installed. See the Hookdeck CLI docs.
• An AWS account with permissions to create Lambda functions and IAM roles.
• A Hookdeck account. Sign up for free 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:

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:

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:

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:

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

Create a Lambda Function URL

You can expose your Lambda function directly using a Function URL 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:

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:

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

You can verify the Function URL is configured correctly:

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

Create a Hookdeck connection

Now, create a Hookdeck connection that routes webhook events from a source to your Lambda function, using AWS Signature authentication.

hookdeck login

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

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

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, 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:

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.

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 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.

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.