Receiving events using Amazon Lambda function URLs - Amazon EventBridge
Set up a connection to GitHubStep 1: Create the Amazon CloudFormation stackStep 2: Create a GitHub webhookSet up a connection to a StripeSet up a connection to a TwilioUpdate webhook secret or auth tokenUpdate Lambda functionAvailable event typesQuotas, error codes, and retrying delivery
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Receiving events using Amazon Lambda function URLs

Note

In order for the Inbound Webhook to be accessible by our partners, we're creating an Open Lambda in your Amazon account that is secured at the Lambda application level by verifying the authentication signature sent by the third-party partner. Please review this configuration with your security team. For more information, see Security and auth model for Lambda function URLs.

Your Amazon EventBridge event bus can use an Amazon Lambda function URL created by an Amazon CloudFormation template to receive events from supported SaaS providers. With function URLs, the event data is sent to a Lambda function. The function then converts this data into an event that can be ingested by EventBridge and sent to an event bus for processing. Once the event is on an event bus, you can use rules to filter the events, apply any configured input transformations, and then route it to the correct target.

Note

Creating Lambda function URLs will increase your monthly costs. For more information, see Amazon Lambda pricing.

To set up a connection to EventBridge, you first select the SaaS provider that you want to set up a connection with. Then, you provide a signing secret that you’ve created with that provider, and select the EventBridge event bus to send events to. Finally, you use an Amazon CloudFormation template and create the needed resources to complete the connection.

The following SaaS providers are currently available for use with EventBridge using Lambda function URLs:

  • GitHub

  • Stripe

  • Twilio

Set up a connection to GitHub

Step 1: Create the Amazon CloudFormation stack

First, use the Amazon EventBridge console to create a CloudFormation stack:

  1. Open the Amazon EventBridge console at https://console.amazonaws.cn/events/.

  2. From the navigation pane, choose Quick starts.

  3. Under Inbound webhooks using Lambda fURLs, choose Get started.

  4. Under GitHub, choose Set up.

  5. Under Step 1: Select an event bus, select an event bus from the dropdown list. This event bus receives data from the Lambda function URL that you provide to GitHub. You can also create an event bus by selecting New event bus.

  6. Under Step 2: Set up using CloudFormation, choose New GitHub webhook.

  7. Select I acknowledge that the Inbound Webhook I create will be publicly accessible. and choose Confirm.

  8. Enter a name for the stack.

  9. Under parameters, verify that the correct event bus is listed, then specify a secure token for the GitHubWebhookSecret. For more information on creating a secure token, see Setting your secret token in the GitHub documentation.

  10. Under Capabilities and transforms, select each of the following:

    • I acknowledge that Amazon CloudFormation might create IAM resources.

    • I acknowledge that Amazon CloudFormation might create IAM resources with custom names.

    • I acknowledge that Amazon CloudFormation might require the following capability: CAPABILITY_AUTO_EXPAND

  11. Choose Create stack.

Step 2: Create a GitHub webhook

Next, create the webhook on GitHub. You’ll need both the secure token and the Lambda function URL you created in step 2 to complete this step. For more information, see Creating webhooks in the GitHub documentation.

Set up a connection to a Stripe

Step 1: Create a Stripe endpoint

To set up a connection between EventBridge and Stripe, first create a Stripe endpoint and note the endpoint secret. You'll use this endpoint secret when you set up your stack in step 2. For more information, see Interactive webhook endpoint builder in the Stripe documentation.

Note

You’ll need a dummy URL to set up the endpoint with Stripe. For example, www.example.com.

Step 2: Create the Amazon CloudFormation stack

  1. Open the Amazon EventBridge console at https://console.amazonaws.cn/events/.

  2. In the navigation pane, choose Quick starts.

  3. Under Inbound webhooks using Lambda fURLs, choose Get started.

  4. Under Stripe, choose Set up.

  5. Under Step 1: Select and event bus, select an event bus from the dropdown list. This event bus receives data from the Lambda function URL that you provide to Stripe. You can also create an event bus by selecting New event bus.

  6. Under Step 2: Set up using CloudFormation, choose New Stripe webhook.

  7. Select I acknowledge that the Inbound Webhook I create will be publicly accessible. and choose Confirm.

  8. Enter a name for the stack.

  9. Under parameters, verify that the correct event bus is listed, then enter the StripeWebhookSecret that you created in Step 1.

  10. Under Capabilities and transforms, select each of the following:

    • I acknowledge that Amazon CloudFormation might create IAM resources.

    • I acknowledge that Amazon CloudFormation might create IAM resources with custom names.

    • I acknowledge that Amazon CloudFormation might require the following capability: CAPABILITY_AUTO_EXPAND

  11. Choose Create stack.

Step 3: Update the Stripe endpoint

Now that you’ve created the Lambda function URL, update the Stripe endpoint to send events to the Lambda function URL.

Set up a connection to a Twilio

Step 1: Find your Twilio auth token

To set up a connection between Twilio and EventBridge, first set up the connection to Twilio with the auth token, or secret, for your Twilio account. For more information, see Auth Tokens and How To Change Them in the Twilio documentation.

Step 2: Create the Amazon CloudFormation stack

  1. Open the Amazon EventBridge console at https://console.amazonaws.cn/events/.

  2. In the navigation pane, choose Quick starts.

  3. Under Inbound webhooks using Lambda fURLs, choose Get started.

  4. Under Twilio, choose Set up.

  5. Under Step 1: Select and event bus, sselect an event bus from the dropdown list. This event bus receives data from the Lambda function URL that you provide to Twilio. You can also create an event bus by selecting New event bus.

  6. Under Step 2: Set up using CloudFormation, choose New Twilio webhook.

  7. Select I acknowledge that the Inbound Webhook I create will be publicly accessible. and choose Confirm.

  8. Enter a name for the stack.

  9. Under parameters, verify that the correct event bus is listed, then enter the TwilioWebhookSecret that you created in Step 1.

  10. Under Capabilities and transforms, select each of the following:

    • I acknowledge that Amazon CloudFormation might create IAM resources.

    • I acknowledge that Amazon CloudFormation might create IAM resources with custom names.

    • I acknowledge that Amazon CloudFormation might require the following capability: CAPABILITY_AUTO_EXPAND

  11. Choose Create stack.

Step 3: Create a Twilio webhook

After you set up the Lambda function URL, you need to give it to Twilio so that event data can be sent. For more information, see Configure your public URL with Twilio in the Twilio documentation.

Update webhook secret or auth token

Update GitHub secret

Note

GitHub doesn’t support having two secrets at the same time. You may experience resource downtime while the GitHub secret and the secret in the Amazon CloudFormation stack are out of sync. GitHub messages sent while the secrets are out of sync will fail becaue of incorrect signatures. Wait until the GitHub and CloudFormation secrets are in sync, then try again.

  1. Create a new GitHub secret. For more information, see Encrypted secrets in the GitHub documentation.

  2. Open the Amazon CloudFormation console at https://console.amazonaws.cn/cloudformation.

  3. From the navigation pane, choose Stacks.

  4. Choose the stack for the webhook that includes the secret you want to update.

  5. Choose Update.

  6. Make sure Use current template is selected and choose Next.

  7. Under GitHubWebhookSecret, clear Use existing value, enter the new GitHub secret you created in step 1, and choose Next.

  8. Choose Next.

  9. Choose Update stack.

It may take up to one hour for the secret to propagate. To reduce this downtime, you can refresh the Lambda execution context.

Update Stripe secret

  1. From the Stripe dashboard, in the Webhooks section, select Roll secret and delay the expiration for at least two(2) hours. For more information, see Roll endpoint secrets in the Stripe documentation.

  2. Open the Amazon CloudFormation console at https://console.amazonaws.cn/cloudformation.

  3. From the navigation pane, choose Stacks.

  4. Choose the stack for the webhook that includes the secret you want to update.

  5. Choose Update.

  6. Make sure Use current template is selected and choose Next.

  7. Under StripeWebhookSecret, clear Use existing value, enter the new Stripe secret you created in step 1, and choose Next.

  8. Choose Next.

  9. Choose Update stack.

Stripe will send both the old signature and the new signature during the rotation period.

Update Twilio secret

Note

Twilio doesn’t support having two secrets at the same time. You may experience resource downtime while the Twilio secret and the secret in the Amazon CloudFormation stack are out of sync. Twilio messages sent while the secrets are out of sync will fail because of incorrect signatures. Wait until the Twilio and CloudFormation secrets are in sync, then try again.

  1. Create a new Twilio secret. For more information, see Auth Tokens and How To Change Them in the Twilio documentation.

  2. Open the Amazon CloudFormation console at https://console.amazonaws.cn/cloudformation.

  3. From the navigation pane, choose Stacks.

  4. Choose the stack for the webhook that includes the secret you want to update.

  5. Choose Update.

  6. Make sure Use current template is selected and choose Next.

  7. Under TwilioWebhookSecret, clear Use existing value, enter the new Twilio secret you created in step 1, and choose Next.

  8. Choose Next.

  9. Choose Update stack.

It may take up to one hour for the secret to propagate. To reduce this downtime, you can refresh the Lambda execution context.

Update Lambda function

The Lambda function that's created by the CloudFormation stack creates the basic webhook. If you want to customize the Lambda function for a specific use case, such as customized logging, use the CloudFormation console to access the function and then use the Lambda console to update the Lambda function code.

Access the Lambda function

  1. Open the Amazon CloudFormation console at https://console.amazonaws.cn/cloudformation.

  2. From the navigation pane, choose Stacks.

  3. Choose the stack for the webhook that includes the Lambda function you want to update.

  4. Choose Resources tab.

  5. To open the Lambda function in the Lambda console, under Physical ID, choose the ID of the Lambda function.

Now that you've accessed the Lambda function, use the Lambda console to update the function code.

Update the Lambda function code

  1. Under Actions, choose Export function.

  2. Choose Download deployment package and save the file to your computer.

  3. Unzip the deployment package .zip file, update the app.py file, and zip the updated deployment package, making sure all the files in the original .zip file are included.

  4. In the Lambda console, choose the Code tab.

  5. Under Code source, choose Upload from.

  6. Choose .zip file, and then choose Upload.

    1. In the file chooser, select the file you updated, choose Open, and then choose Save.

  7. Under Actions, choose Publish new version.

Available event types

The following event types are currently supported by CloudFormation event buses:

Quotas, error codes, and retrying delivery

Quotas

The number of incoming requests to the webhook is capped by the underlying Amazon services. The following table includes the relevant quotas.

Service Quota

Amazon Lambda

Default: 10 concurrent executions

For more information about quotas, including requesting quota increases, see Lambda quotas.

Amazon Secrets Manager

Default: 5,000 requests per second

For more information about quotas, including requesting quota increases, see Amazon Secrets Manager quotas.

Note

The number of requests per second is minimized using the Amazon Secrets Manager Python caching client.

Amazon EventBridge

256KB maximum entry size for PutEvents actions.

EventBridge enforces Region-based rate quotas. For more information, see EventBridge quotas.

Error codes

Each Amazon service returns specific error codes when errors occur. The following table includes the relevant error codes.

Service Error code Description

Amazon Lambda

429 “TooManyRequestsExption”

The concurrent execution quota is exceeded.

Amazon Secrets Manager

500 “Internal Server Error”

The requests per second quota is exceeded.

Amazon EventBridge

500 “Internal Server Error”

The rate quota is exceeded for the Region.

Event redelivery

When errors happen you can retry delivery of the affected events. Each SaaS provider has different retry procedures.

GitHub

Use the GitHub webhooks API to check the deliver status of any webhook call and redeliver the event, if needed. For more information, see the following GitHub documentation:

Stripe

Stripe attempts to deliver your webhooks for up to three days with an exponential back off. For more information, see the following Stripe documentation:

Twilio

Twilio users can customize event retry options using connection overrides. For more information, see Webhooks (HTTP callbacks): Connection Overrides in the Twilio documentation.