This project is a serverless application that receives a webhook via POST or GET HTTP method, sends the raw received data to the SNS topic, and replies with the 200 OK
response to the webhook sender.
The architecture for this app looks like the following diagram:
This app contains the following components:
- An API Gateway HTTP API endpoint - a new API Gateway HTTP API is cheaper and less powerful than the REST API, but it has everything we need for the common webhook.
- A Lambda Function - that we use to process the request, send it to the SNS topic, and immediately return the
200 OK
response to the API Gateway. - An SNS topic - that webhook events are sent to, you can connect rest of your application to this webhook.
You can deploy this app from Serverless Application Repository (SAR) or manually, using the Serverless Application Model Command Line Interface (SAM CLI).
Go to the Generic webhook to SNS App on the AWS Serverless App repo, click Deploy and follow the wizard to configure the app.
Or use with AWS SAM by adding the following resource:
GenericWebhookToSns:
Type: AWS::Serverless::Application
Properties:
Location:
ApplicationId: arn:aws:serverlessrepo:us-east-1:721177882564:applications/generic-webhook-to-sns
SemanticVersion: 1.0.0
The SAM CLI is an extension of the AWS CLI that adds functionality for building and testing Lambda applications. It uses Docker to run your functions in an Amazon Linux environment that matches Lambda. It can also emulate your application's build environment and API.
To use the SAM CLI, you need the following tools.
- SAM CLI - Install the SAM CLI
- Node.js - Install Node.js 10, including the NPM package management tool.
- Docker - Install Docker community edition
To build and deploy your application for the first time, run the following in your shell:
yarn run build
sam deploy --guided
The first command will build the source of your application. The second command will package and deploy your application to AWS, with a series of prompts.
You can find your API Gateway Endpoint URL in the output values displayed after deployment.
You can use Generic webhook to SNS topic application in your SAM application by adding it as a nested app in your SAM template.
A minimal template can look similar to the following one:
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: A cool SAM app
Globals:
Function:
Timeout: 10
Runtime: nodejs12.x
Resources:
Webhook:
Type: AWS::Serverless::Application
Properties:
Location:
ApplicationId: arn:aws:serverlessrepo:us-east-1:721177882564:applications/generic-webhook-to-sns
SemanticVersion: 1.0.0
WebhookFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: build/webhook
Handler: lambda.handler
Events:
WebhookEventNotification:
Type: SNS
Properties:
Topic: !GetAtt Webhook.Outputs.WebhookTopicArn
Outputs:
WebhookUrl:
Description: "Webhook URL"
Value: !GetAtt Webhook.Outputs.WebhookApiUrl
This will deploy the Webhook app from SAR and a Lambda function that will be triggered when a webhook event is received.
Important parts of the template:
Webhook (AWS::Serverless::Application)
is a resource that deploys a Generic webhook to SNS topic app from SARApplicationId: arn:aws:serverlessrepo:eu-central-1:123456789012:applications/generic-webhook-to-sns
is a SAR app ARN (see the Install from SAR section).Topic: !GetAtt Webhook.Outputs.WebhookTopicArn
get's aWebhookTopicArn
output attribute from the SAR app.
In production, you should consider adding a few more things, such as:
- Lambda destinations or dead letter queue for handling errors
- Enable monitoring (i.e., Amazon X-Ray)
- Assigning a custom domain/path to your webhook
An SNS notification sent by the application will have the following properties:
- Message: A stringified API Gateway HTTP API event.
- MessageAttributes: An SNS notification will optionally contain the following Message Attribute (used for filtering):
- MessageType: An attribute that contains the the string value you can filter by. For example, for Stripe "invoice.upcoming" event, you'll receive the following Message Attributes:
{MessageType: { DataType: 'String', StringValue: 'invoice.upcoming'}
.
- MessageType: An attribute that contains the the string value you can filter by. For example, for Stripe "invoice.upcoming" event, you'll receive the following Message Attributes:
MIT, see LICENSE.