README.md

Mailgun Webhook AWS Lambda DyanamoDB and SNS Notification Service

Table of Contents

• Summary of Features
• Code Execution
• How to Test
• Features
  • AWS DynamoDB
  • AWS SNS Notification
  • AWS CloudFormation
  • AWS Codebuild CI/CD
• Github Token and Mailgun Webhook Signing Token

Summary of Features

• Saving in AWS DynamoDB of Mailgun Webhook details received via AWS API Gateway
• AWS SNS publish of Mailgun Webhook details to subscribed emails
• AWS CloudFormation automatic creation of required AWS resources to run this repo (via bash script).
• AWS Codebuild CI/CD auto-update of AWS Lambda function upon merge of commits to this Github repo

Execution / Deployment via AWS CodeFormation (Auto-creation of AWS Resources)

To create the necessary AWS resources, this repo implements infracstructure by code via CloudFormation.

You need to have AWS CLI and Yarn installed in your system to execute the script file.

Run the following:

chmod u+x create-cf-stacks.sh
./create-cf-stacks.sh

This script will automate the creation of the required AWS resources (S3, Lambda, API Gateway, DynamoDB, SNS, CodeBuild, IAM Roles, etc).

Once executed the terminal will prompt you for the Github Auth Token, Mailgun Webhook Signing Key and Email to be used for subscription.

Details about the Github Token and Mailgun Signing key will be discussed here.

You can customize the AWS resources by updating the variables section of create-sf-stacks.sh

How to Test

After executing the create-cf-stacks.sh scripts you can test the application by sending a mailgun webhook. To do this follow the following steps:

Confrim SNS Subscription

Go to the email you provided and confirm subscription to SNS Topic.

Copy AWS API Gateway URL for mailgunwebhook.

Go to your AWS API Gateway Page and click on MailGunWebhook API.

Go to Stages > / > /mailgunwebhook > POST and copy the Invoke URL.

Test Using Mailgun.com

Go and login to Mailgun.com.

Once logged in go to Sending > Webhooks on the right navigation panel.

Paste the copied API Gateway URL and click Test webhook.

Once tested you will receive a response coming from our AWS Lambda Function.

Features

Mailgun Webhook Processing

Once a the webhook is received by our Gateway API and processed by our Lambda this app will do the following:

Saving of sent Mailgun webhook in DynamoDB.

Sending of AWS SNS Notification to subscribed email/s

Automatic CloudFormation Deploy of Application Stacks (Automatic AWS allocation of resources).

The create-cf-stacks.sh script will automatically create all the required AWS resources when executed. No more time consuming creation/integration of AWS resources via CLI or Online Console.

Auto-update of AWS Lambda Function

Our deployment is integrated to this Github repo's main branch via AWS CodeBuild. Any PR merged to the main branch of this repo will trigger a build/update of our AWS Lambda. See buildspec.yml.

Acquiring Github Auth Token and Mail Gun Webhook Signing Key

Github Auth Token

The Github Token will be used for connecting your AWS account to Github account for CodeBuild configurations. CodeBuild will track Github repo's main branch to update the AWS Lambda function.

Go to New Personal Access Tokens (Classic) Page.

Replicate the following configuration shown on the images.

Then Generate token and copy the token for create-cf-stacks.sh prompt.

Mailgun Webhook Sigining Key

The Mailgun webhook signing key is used to verify that the hooks received by AWS Lambda via API gateway are coming from the Mailgun account of the user.

To get Mailgun webhook signing key go and login to Mailgun.com.

Once logged in go to Sending > Webhooks on the right navigation panel.

On this page you will see the HTTP webhook signing key. Copy this for the create-cf-stacks.sh prompt.