Building Slack Bots for Fun: A Serverless Release Gong
We have a running joke at Stackery regarding our tiny little gong that’s used to mark the occasion when we get a new customer.
So tiny.
And while I’m all about the sales team celebrating their successes (albeit with a far-too-small gong), I felt like the dev team needed its own way to commemorate major product releases and iterations.
Then I saw that Serverless Framework is doing its No Server November challenge, and I thought, what a perfect way to show off our multiple framework support while iterating on our Github Webhooks Tutorial to support Serverless Framework projects!
Starting from Scratch…Almost
Stackery makes it easy to import an existing stack or create new a stack based on an existing template. And, conveniently, I had already build a GitHub webhook listener just the week before as part of the webhook tutorial. However, the rules of the competition specifically state that “to qualify, the entry must use the Serverless Framework and a serverless backend” - and I was curious to see the differences when building out my app using that framework as compared to our default (AWS SAM).
So the first thing I did was create an empty Serverless Framework template I could use to build my app on. This was quite simple - I just created a serverless.yml file in a new directory and added the following:
service: serverless-gong
frameworkVersion: ">=1.4.0 <2.0.0"
provider:
name: aws
runtime: nodejs8.10
I initialized a new git repository, and added, committed and pushed the serverless.yml file to it.
Building in Stackery
Now it was time to import my new Serverless Framework boilerplate into Stackery so I could start adding resources. In the Stackery App, I navigated to my Stacks page, and clicked the Create New Stack button in the upper right, filling it out like so:
Then, in the Stackery Dashboard, I created an API Gateway resource with a POST route with a /webhook path and a Function resource named handleGong, and connected them with a wire. All of this, including saving and using environment variables for your GitHub secret, is documented in the webhook tutorial, so I won’t go through it again. In the end, I had a setup very similar to that found at the end of that tutorial, with the exception of having a serverless.yml file rather than a template.yml for the configuration, and having everything in one directory (which was fine for a small project like this, but not ideal in the long run).
With the added resources, my serverless configuration now looked like this:
service: serverless-gong
frameworkVersion: '>=1.4.0 <2.0.0'
provider:
name: aws
runtime: nodejs8.10
functions:
handleGong:
handler: handler.gongHandler
description:
Fn::Sub:
- 'Stackery Stack #{StackeryStackTagName} Environment #{StackeryEnvironmentTagName} Function #{ResourceName}'
- ResourceName: handleGong
events:
- http:
path: /webhook
method: POST
environment:
GITHUB_WEBHOOK_SECRET:
Ref: StackeryEnvConfiggithubSecretAsString
SLACK_WEBHOOK_URL:
Ref: StackeryEnvConfigslackWebhookURLAsString
resources:
Parameters:
StackeryStackTagName:
Type: String
Description: Stack Name (injected by Stackery at deployment time)
Default: serverless-gong
StackeryEnvironmentTagName:
Type: String
Description: Environment Name (injected by Stackery at deployment time)
Default: dev
StackeryEnvConfiggithubSecretAsString:
Type: AWS::SSM::Parameter::Value<String>
Default: /Stackery/Environments/<StackeryEnvId>/Config/githubSecret
StackeryEnvConfigslackWebhookURLAsString:
Type: AWS::SSM::Parameter::Value<String>
Default: /Stackery/Environments/<StackeryEnvId>/Config/slackWebhookURL
Metadata:
StackeryEnvConfigParameters:
StackeryEnvConfiggithubSecretAsString: githubSecret
StackeryEnvConfigslackWebhookURLAsString: slackWebhookURL
plugins:
- serverless-cf-vars
Look at all that yaml I didn't write!
And my Dashboard looked like so:
Since I had already written a webhook starter function that at the moment logged to the console, it didn’t feel necessary to reinvent the wheel, so I committed in Stackery, then git pulled my code to see the updates, and created a handler.js file in the same directory as the serverless.yml. In it, I pasted the code from my previous webhook function - this was going to be my starting point:
const crypto = require('crypto');
function signRequestBody(key, body) {
return `sha1=${crypto.createHmac('sha1', key).update(body, 'utf-8').digest('hex')}`;
}
// The webhook handler function
exports.gongHandler = async event => {
// get the GitHub secret from the environment variables
const token = process.env.GITHUB_WEBHOOK_SECRET;
const calculatedSig = signRequestBody(token, event.body);
let errMsg;
// get the remaining variables from the GitHub event
const headers = event.headers;
const sig = headers['X-Hub-Signature'];
const githubEvent = headers['X-GitHub-Event'];
const body = JSON.parse(event.body);
// this determines username for a push event, but lists the repo owner for other events
const username = body.pusher ? body.pusher.name : body.repository.owner.login;
const message = body.pusher ? `${username} pushed this awesomeness/atrocity through (delete as necessary)` : `The repo owner is ${username}.`
// get repo variables
const { repository } = body;
const repo = repository.full_name;
const url = repository.url;
// check that a GitHub webhook secret variable exists, if not, return an error
if (typeof token !== 'string') {
errMsg = 'Must provide a \'GITHUB_WEBHOOK_SECRET\' env variable';
return {
statusCode: 401,
headers: { 'Content-Type': 'text/plain' },
body: errMsg,
};
}
// check validity of GitHub token
if (sig !== calculatedSig) {
errMsg = 'X-Hub-Signature incorrect. Github webhook token doesn\'t match';
return {
statusCode: 401,
headers: { 'Content-Type': 'text/plain' },
body: errMsg,
};
}
// print some messages to the CloudWatch console
console.log('---------------------------------');
console.log(`\nGithub-Event: "${githubEvent}" on this repo: "${repo}" at the url: ${url}.\n ${message}`);
console.log('Contents of event.body below:');
console.log(event.body);
console.log('---------------------------------');
// return a 200 response if the GitHub tokens match
const response = {
statusCode: 200,
body: JSON.stringify({
input: event,
}),
};
return response;
};
At this point, I prepared and did the initial deploy of my stack in order to get the Rest API endpoint for the GitHub webhook I needed to set up. Again, the webhook tutorial runs through the deployment and webhook setup process step by step, so I won’t repeat it here.
Using the Rest API /webhook url, I created a webhook in our Stackery CLI repo that was now listening for events, and I confirmed in my CloudWatch logs that it was indeed working.
Bring on the Gong
The next step was to modify the function so it “gonged” our Slack channel when our Stackery CLI repo was updated with a new release. To do that, I had to create a custom Slack app for our channel and set up its incoming webhooks. Luckily, Slack makes that really easy to do, and I just followed the step-by-step instructions in Slack’s webhook API guide to get going.
I set up a #gong-test channel in our Slack for testing so as to not annoy my co-workers with incessant gonging, and copied the URL Slack provided (it should look something like https://hooks.slack.com/services/T00000000/B00000000/12345abcde).
Before editing the Lambda function itself, I needed a way for it to reference that URL as well as my GitHub secret without hard-coding it in my function that would then be committed to my public repo (because that is a Very Bad Way to handle secrets). This is where Stackery Environments come in handy.
I saved my GitHub secret and Slack URL in my environment config like so:
Then referenced it in my function:
And will add it to my function code in the next step, using process.env.GITHUB_WEBHOOK_SECRET and process.env.SLACK_WEBHOOK_URL as the variables.
Final Ingredient
Since we’re automating our gong, what’s more appropriate than an automated gong? After a somewhat frustrating YouTube search, I found this specimen:
A auto-gong for our automated app? Perfect! Now let’s use our function to send that gong to our Slack channel.
Here’s the code for the final gongHandler function in handler.js:
const crypto = require('crypto');
const Slack = require('slack-node');
// validate your payload from GitHub
function signRequestBody(key, body) {
return `sha1=${crypto.createHmac('sha1', key).update(body, 'utf-8').digest('hex')}`;
}
// webhook handler function
exports.gongHandler = async event => {
// get the GitHub secret from the environment variables
const token = process.env.GITHUB_WEBHOOK_SECRET;
const calculatedSig = signRequestBody(token, event.body);
let errMsg;
// get the remaining variables from the GitHub event
const headers = event.headers;
const sig = headers['X-Hub-Signature'];
const githubEvent = headers['X-GitHub-Event'];
const body = JSON.parse(event.body);
// get repo variables
const { repository, release } = body;
const repo = repository.full_name;
const url = repository.url;
// set variables for a release event
let releaseVersion, releaseUrl, author = null;
if (githubEvent === 'release') {
releaseVersion = release.tag_name;
releaseUrl = release.html_url;
author = release.author.login;
}
// check that a GitHub webhook secret variable exists, if not, return an error
if (typeof token !== 'string') {
errMsg = 'Must provide a \'GITHUB_WEBHOOK_SECRET\' env variable';
return {
statusCode: 401,
headers: { 'Content-Type': 'text/plain' },
body: errMsg,
};
}
// check validity of GitHub token
if (sig !== calculatedSig) {
errMsg = 'X-Hub-Signature incorrect. Github webhook token doesn\'t match';
return {
statusCode: 401,
headers: { 'Content-Type': 'text/plain' },
body: errMsg,
};
}
// if the event is a 'release' event, gong the Slack channel!
const webhookUri = process.env.SLACK_WEBHOOK_URL;
const slack = new Slack();
slack.setWebhook(webhookUri);
// send slack message
if (githubEvent === 'release') {
slack.webhook({
channel: "#gong-test", // your desired channel here
username: "gongbot",
icon_emoji: ":gong:", // because Slack is for emojis
text: `It's time to celebrate! ${author} pushed release version ${releaseVersion}. See it here: ${releaseUrl}!\n:gong: https://youtu.be/8nBOF5sJrSE?t=11` // your message
}, function(err, response) {
console.log(response);
if (err) {
console.log('Something went wrong');
console.log(err);
}
});
}
// (optional) print some messages to the CloudWatch console (for testing)
console.log('---------------------------------');
console.log(`\nGithub-Event: "${githubEvent}" on this repo: "${repo}" at the url: ${url}.`);
console.log(event.body);
console.log('---------------------------------');
// return a 200 response if the GitHub tokens match
const response = {
statusCode: 200,
body: JSON.stringify({
input: event,
}),
};
return response;
};
Finally, I needed to add a package.json file so that I could use dependencies. When creating a function using an AWS SAM template, Stackery would do this for your automatically, but in this case I had to create the file and add the following myself:
{
"private": true,
"dependencies": {
"aws-sdk": "~2",
"slack-node": "0.1.8"
}
}
I added, committed and pushed the new code, re-deployed my Serverless Framework stack, then added another GitHub webhook to a test repo. I created a GitHub release in my test repo, and waited in anticipation.
Milliseconds later, I hear the familiar click-click-click of Slack…
Pretty awesome, if I do say so myself. 🔔
A few notes:
- I used the slack-node NPM package to make life easier. I could have used the requests library or the built-in HTTPS library (and you can if you want to avoid using external dependencies).
- The GitHub API is very helpful for figuring out what kind of response to expect from your webhook. That’s how I determined the values to set for
releaseVersion, releaseUrl, author. - When you
console.log()in your serverless function, the results can be seen in the AWS CloudWatch logs. Stackery provides a convenient direct link for each function.
- This serverless application should fit within your AWS free tier, but keep an eye on your logs and billing just in case.
If you’d like to make your own serverless gong, all of the configuration code is available in my Serverless Gong GitHub repository. Just create a new stack your Stackery account (you can sign up for a free trial if you don’t have one yet), choose Create New Repo as the Repo Source, and select Specify Remote Source to paste in the link to my repo as a template.
Add your GitHub and Slack environment parameters, deploy your stack, and sit back and wait for your Slack to gong!
As a part of the approval process, Stackery had to meet Amazon’s strict requirements for security, site reliability, disaster recovery and customer data protection. This means that Stackery customers have the assurance that their 
