<h2 id="content"><a href="#content" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>Content</h2>
<ul>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#architecture---aws">Architecture - AWS</a>
<ul>
<li><a href="#webhook-sequence">Webhook Sequence</a></li>
</ul>
</li>
<li><a href="#authentication">Authentication</a></li>
<li><a href="#lambda-event-in-take">Lambda Event In-take</a>
<ul>
<li><a href="#sqs-queue">SQS (Queue)</a></li>
<li><a href="#event-triggers">Event triggers</a></li>
</ul>
</li>
<li><a href="#technical-series">Technical Series</a>
<ol>
<li><a href="#1-setup-infrastructure-for-the-lambda-function">Setup infrastructure for the Lambda function</a></li>
<li><a href="#2-setup-the-cicd-for-the-lambda-functions">Setup the CI/CD for the Lambda functions</a></li>
<li><a href="#3-setup-up-aws-api-gateway-sqs-integrate-with-lambda-and-dlq">Setup up AWS API Gateway SQS, integrate with Lambda and DLQ</a></li>
<li><a href="#4-setup-the-code-for-the-ingestion-and-processing-lambda">Setup the code for the ingestion and processing lambda</a></li>
<li><a href="#5-service-health-and-performance">Service health and performance</a></li>
<li><a href="#6-error-handling-in-aws-lambda">Error handling in AWS Lambda</a></li>
</ol>
</li>
</ul>
<h2 id="introduction"><a href="#introduction" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>Introduction</h2>
<p>In this technical series, we will be building out a common solution used in many applications - a webhook endpoint.</p>
<p>This allows for service-to-service communication in your application or with a third party service.</p>
<p>We will go through setting up the infrastructure using AWS, code using Node.js, security and much more.</p>
<p>Beyond just receiving events through an endpoint, we can also leverage this pattern to process tasks in the background.</p>
<p><strong>This provides several advantages such as:</strong></p>
<ul>
<li>Decoupled architecture
<ul>
<li>Makes it easier for security hardening and auditing</li>
<li>Allows for independent scaling</li>
</ul>
</li>
<li>Better reliability (Handling of failures - errors, timeouts and rate limits etc)</li>
<li>Resilience to handling unpredictable work loads (ie Traffic spikes)</li>
</ul>
<h2 id="architecture---aws"><a href="#architecture---aws" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>Architecture - AWS</h2>
<p>In terms of architecture, we will be creating a public api endpoint, that is gated by AWS Cognito, which gives us the ability to add events to the queue then have it processed at a later time.</p>
<p><strong>The architecture will be divided into two distinct sections:</strong></p>
<ul>
<li><strong>Event in-take</strong> - Handling the request to add an event to the queue</li>
<li><strong>Event processing</strong> - Processing the event out of process at a later time (then re-trying as needed during failures)</li>
</ul>
<div style="display:flex; justify-content:center;margin: 2rem auto;">
  <img src="/images/og-webhook-step-by-step-guide-to-integrate-a-webhook-with-github-using-aws.png" alt="Webhook full infrastructure integrating with Github">
</div>
<h3 id="webhook-sequence"><a href="#webhook-sequence" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>Webhook Sequence</h3>
<ol>
<li>
<p>The 3rd party service (ie Github) generates a signature using a shared key with SHA-256</p>
</li>
<li>
<p>The 3rd party service then makes a HTTP request to the webhook endpoint with the payload and signature</p>
</li>
<li>
<p>The AWS API gateway invokes the AWS Lambda Alias (associated with the Ingestion AWS Lambda function)</p>
</li>
<li>
<p>The Ingestion AWS Lambda function verifies the signature</p>
</li>
<li>
<p>The Ingestion AWS Lambda add the new message to the AWS SQS</p>
</li>
<li>
<p>AWS SQS triggers the AWS Alias (associated with the Process Queue AWS Lambda function) with the new message to be processed</p>
</li>
<li>
<p><strong>[Optional]</strong> Failures in the Process Queue AWS Lambda function will be added to the Dead-Letter Queue (DLQ) to be retried</p>
</li>
</ol>
<p>Let’s go through each part of the infrastructure in a bit more detail.</p>
<h3 id="authentication"><a href="#authentication" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>Authentication</h3>
<p>The Authentication for our webhook will use HS256 which stands for HMAC using SHA-256.</p>
<p>This allows us to establish a trusted relationship between the 3rd party service and our API endpoint so we can ensure that the payload we receive is coming from a valid source.</p>
<p>Throughout the series, we will go through the details on how to implement this using Node.js.</p>
<h3 id="lambda-event-in-take"><a href="#lambda-event-in-take" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>Lambda (Event in-take)</h3>
<p>Once authorized, the api gateway will call the lambda alias which will trigger the “ingestion” lambda. This will basically just add the event to our in-take queue.</p>
<h4 id="sqs-queue"><a href="#sqs-queue" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>SQS (queue)</h4>
<p>We are using SQS for our event in-take and dead-letter queues (DLQ).</p>
<h4 id="event-triggers"><a href="#event-triggers" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>Event triggers</h4>
<p>Once an event is added to the queue, it will trigger the ”processing” lambda.</p>
<p>This will allow us to process the event that was added to the queue using our lambda function.</p>
<p>This can be sending an email, relaying to another channel (discord or slack) or any other tasks.</p>
<h2 id="technical-series"><a href="#technical-series" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>Technical series</h2>
<h3 id="1-setup-infrastructure-for-the-lambda-function"><a href="#1-setup-infrastructure-for-the-lambda-function" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>1. Setup infrastructure for the Lambda function</h3>
<p><a href="https://www.jerrychang.ca/writing/build-a-webhook-microservice-using-aws-technical-series-lambda-infrastructure" target="_blank" rel="nofollow noopener noreferrer">Build a webhook microservice using AWS Technical series Part I</a></p>
<p>In this module, we will be scaffolding out our lambda functions then testing the CI/CD manually from our local environment.</p>
<p>This is in preparation for automating the process in Github actions (next module).</p>
<p>The CI/CD will add the assets to the s3 buckets then that will be used to publish a new lambda function version then the lambda alias will be updated with the new version.</p>
<div style="display:flex; justify-content:center;margin: 2rem auto;">
  <img src="/images/webhook-lambda-infrastructure.png" alt="webhook lambda infrastructure">
</div>
<h3 id="2-setup-the-cicd-for-the-lambda-functions"><a href="#2-setup-the-cicd-for-the-lambda-functions" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>2. Setup the CI/CD for the Lambda functions</h3>
<p><a href="https://www.jerrychang.ca/writing/how-to-secure-your-aws-lambda-deployments-using-github-actions-and-oidc-in-7-easy-steps" target="_blank" rel="nofollow noopener noreferrer">How To Secure Your AWS Deployments Using Github Actions and OIDC In 7 Easy Steps</a></p>
<p>In this module, we will be setting up the CI/CD for our lambda functions which will take the new changes we pushed all the way live to the lambda function.</p>
<p>This will go through the process of building, testing, and deploying.</p>
<p>As part of this setup, we will be writing our the github workflows and setting up the Open ID connect with Github &#x26; AWS with the correct IAM permissions.</p>
<p>Once this is all setup, we should have an automated pipeline that will deploy our changes to our <code class="language-">dev
</code> alias when we push our code in both of our functions!</p>
<div style="display:flex; justify-content:center;margin: 2rem auto;">
  <img src="/images/webhook-ci-cd-architecture.png" alt="webhook lambda CI/CD infrastructure">
</div>
<h3 id="3-setup-up-aws-api-gateway-sqs-integrate-with-lambda-and-dlq"><a href="#3-setup-up-aws-api-gateway-sqs-integrate-with-lambda-and-dlq" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>3. Setup up AWS API Gateway SQS, integrate with Lambda and DLQ</h3>
<p><a href="https://www.jerrychang.ca/writing/setup-api-gateway-sqs-with-aws-lambda" target="_blank" rel="nofollow noopener noreferrer">Setup API Gateway and SQS with AWS Lambda</a></p>
<p>In this module, we will setup both the in-take and re-procesing (DLQ) SQS queue.</p>
<p>Then, we will connect that via an event trigger to call the “processing” lambda whenever an event is added to the queue.</p>
<div style="display:flex; justify-content:center;margin: 2rem auto;">
  <img src="/images/webhook-sqs-dlq-lambda-infrastructure.png" alt="webhook sqs with lambda and DLQ infrastructure">
</div>
<h3 id="4-setup-the-code-for-the-ingestion-and-processing-lambda"><a href="#4-setup-the-code-for-the-ingestion-and-processing-lambda" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>4. Setup the code for the ingestion and processing lambda</h3>
<p><a href="https://www.jerrychang.ca/writing/step-by-step-guide-to-integrate-a-webhook-with-github-using-aws" target="_blank" rel="nofollow noopener noreferrer">Step-By-Step Guide to integrate a webhook with Github using AWS</a></p>
<p>In this module, we will code out all the logic for our ”ingestion” and ”processing” lambda.</p>
<p>Then we will integrate it with Github webhooks to see it in action!</p>
<div style="display:flex; justify-content:center;margin: 2rem auto;">
  <img src="/images/og-webhook-step-by-step-guide-to-integrate-a-webhook-with-github-using-aws.png" alt="webhook sqs with lambda and DLQ infrastructure">
</div>
<p><strong>This will include:</strong></p>
<ul>
<li>Code structure</li>
<li>Error handling</li>
<li>Event validation</li>
<li>Logic for adding into the queue</li>
<li>Guarding against SQS size limits (256kb)</li>
<li>Webhook payload signature verification (SHA-256)</li>
<li>And much more...</li>
</ul>
<p>Then, we will connect that via an event trigger to call the “processing” lambda whenever an event is added to the queue.</p>
<h3 id="5-service-health-and-performance"><a href="#5-service-health-and-performance" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>5. Service health and performance</h3>
<ul>
<li>
<p>Overview: <a href="https://www.jerrychang.ca/writing/service-health-and-performance-for-aws-webhook-infrastructure" target="_blank" rel="nofollow noopener noreferrer">A pocket guide to service health and performance for AWS API gateway, Lambda, SQS</a></p>
</li>
<li>
<p>Implementation Guide: <a href="https://www.jerrychang.ca/writing/practical-guide-to-service-health-and-performance-for-aws" target="_blank" rel="nofollow noopener noreferrer">Practical Guide: Tracing and Logging for Node.js using AWS Lambda</a></p>
</li>
</ul>
<div style="display:flex; justify-content:center;margin: 2rem auto;">
  <img src="/images/webhook-service-tracing.png" alt="Webhook infrastructure tracing">
</div>
<p>Now we have a fully functional service, let’s take a look at how to handle upkeep and service health.</p>
<p>We have to have proper instrumentation in place in order to better understand how our service is doing in production.</p>
<p>In this module, we’ll explore the important metrics to look out for in our infrastructure.</p>
<p>Also, we’ll see how we can integrate different tooling and techniques to debug, measure and benchmark performance.</p>
<p><strong>These could include things like:</strong></p>
<ul>
<li>Tracing</li>
<li>Logging</li>
<li>Metrics</li>
<li>Performance benchmarking</li>
</ul>
<h2 id="6-error-handling-in-aws-lambda"><a href="#6-error-handling-in-aws-lambda" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>6. Error handling in AWS Lambda</h2>
<p><a href="https://www.jerrychang.ca/writing/aws-lambda-the-structured-approach-to-simple-and-testable-code" target="_blank" rel="nofollow noopener noreferrer">AWS Lambda: The structured approach to simple and testable code</a></p>
<div style="display:flex; justify-content:center;margin: 2rem auto;">
  <img src="/images/lambda-response-mindmap.png" alt="AWS Lambda response outcomes" style="width:75%;">
</div>
<p>As noted in our scaffold, we will be layering in error handling as a final touch.</p>
<p>By the end of this module, we should have an error handler that is simple, easy to test and extend.</p>
<p>We’ll not only go through the implementation but also the design to lead us to the end result!</p>


A technical series on AWS solution to build a webhook service

Jerry Chang

Go Back

Build a webhook microservice using AWS

Enjoy the content ?