AWS Lambda Pivotal-to-HipChat filter

An AWS Lambda function for filtering and transforming Pivotal activity web hook (v5) notifications and posting them to a HipChat room. We find this cleaner and more flexible than the official HipChat Pivotal endpoint (https://confluence.atlassian.com/display/HIPCHATKB/Pivotal+Tracker+integration).

Important note: for this integration, you will need to use HipChat API v1 tokens.

Initial set up

This needs to be done once using the AWS CLI commands below or the equivalent AWS Console operations.

# Set env vars for AWS CLI
$ export AWS_ACCESS_KEY_ID=...
$ export AWS_SECRET_ACCESS_KEY=...
$ export AWS_DEFAULT_REGION=...
$ export AWS_ACCOUNT=...

# Create AIM role for function
...DOC TODO...
$ export AWS_LAMBDA_ROLE_ARN=...

# Create the function itself
$ aws lambda create-function \
	--function-name postToHipChatFromPivotal \
	--runtime nodejs \
	--role ${AWS_LAMBDA_ROLE_ARN} \
	--handler index.handler
$ export AWS_LAMBDA_FUNCTION_ARN=... # lookup in the output above

# Create the API endpoint
$ aws apigateway create-rest-api \
	--name "pivotalToHipChat"
$ export AWS_APIGATEWAY_ID=... # lookup in the output above

$ aws apigateway get-resources \
	--rest-api-id ${AWS_APIGATEWAY_ID}
$ export AWS_APIGATEWAY_RESOURCE_ID=... # lookup root resource id in the output above

$ aws apigateway put-method \
	--rest-api-id ${AWS_APIGATEWAY_ID} \
	--resource-id ${AWS_APIGATEWAY_RESOURCE_ID} \
	--http-method POST \
	--authorization-type none \
	--request-parameters '{ "method.request.querystring.hipchatToken": false, "method.request.querystring.hipchatRoom": false }'

$ aws apigateway put-integration 
	--rest-api-id ${AWS_APIGATEWAY_ID} \
	--resource-id ${AWS_APIGATEWAY_RESOURCE_ID} \
	--http-method POST \
	--type AWS \
	--integration-http-method POST \
	--uri arn:aws:apigateway:${AWS_DEFAULT_REGION}:lambda:path/2015-03-31/functions/${AWS_LAMBDA_FUNCTION_ARN}/invocations \
	--request-templates '{ "application/json": "{\"hipchatToken\" : \"$util.urlDecode($input.params('\''hipchatToken'\''))\", \"hipchatRoom\" : \"$util.urlDecode($input.params('\''hipchatRoom'\''))\", \"activity\" : $input.json('\''$'\'')}"}'

$ aws apigateway put-integration-response \
	--rest-api-id ${AWS_APIGATEWAY_ID} \
	--resource-id ${AWS_APIGATEWAY_RESOURCE_ID} \
	--http-method POST \
	--status-code 200 \
	--response-templates '{ "application/json": "" }'

$ aws apigateway put-method-response \
	--rest-api-id ${AWS_APIGATEWAY_ID} \
	--resource-id ${AWS_APIGATEWAY_RESOURCE_ID} \
	--http-method POST \
	--status-code 200 \
	--response-models '{ "application/json": "Empty" }'

$ aws apigateway create-deployment \
	--rest-api-id ${AWS_APIGATEWAY_ID} \
    --stage-name prod

$ aws lambda add-permission \
	--function-name postToHipChatFromPivotal \
	--statement-id 1 \
	--action lambda:InvokeFunction \
	--principal apigateway.amazonaws.com \
	--source-arn "arn:aws:execute-api:${AWS_DEFAULT_REGION}:${AWS_ACCOUNT}:${AWS_APIGATEWAY_ID}/*/POST/"

$ export AWS_LAMBDA_FUNCTION_URL=https://${AWS_APIGATEWAY_ID}.execute-api.${AWS_DEFAULT_REGION}.amazonaws.com/prod

Development loop

After the steps above, it should be possible run make to deploy and test the function (after setting HIPCHAT_TOKEN and HIPCHAT_ROOM):

$ make deploy
$ HIPCHAT_TOKEN=... HIPCHAT_ROOM=... make posttest

(If your HipChat room name contains non-URL-safe characters (such as spaces), it will need to be URL-encoded for the above to work).

Alternatively, you can run the tests locally without deploying:

$ HIPCHAT_TOKEN=... HIPCHAT_ROOM=... make localtest

Both tests will use the fixtures declared inside the Makefile. make localtest will also validate the logic for skipping certain state transitions that we didn't find useful to blast to the team.

Integrate into Pivotal

To integrate your filter into your Pivotal project, set your activity web hook URL on the project's Integrations settings page to:

$(AWS_LAMBDA_FUNCTION_URL)?hipchatToken=...&hipchatRoom=...

Again, remember to use your HipChat API v1 token and URL-encode the room name, if necessary.