impact-helper-api

An API for integrating between HubSpot CRM, Upright and Slack

Requirements

• Upright organisational account
• HubSpot Sales Hub Professional or Enterprise
• Slack workspace
• Redis running on port 6379 (unless using AWS Lambda environment)

How it works

The API takes in a HubSpot Deal, finds an Upright profile for the Company associated with the Deal, and returns the Upright profile.

POST /webhooks/hubspot/deals

Example body:

{
  "objectId": "1234567890"
}

200 response:

ok

objectId is the ID of the Deal in HubSpot (visible in the URL when you open the deal). You can set up a webhook to this URL in GitHub Actions for some Deal trigger to automatically send an Upright profile to Slack whenever that trigger fires.

This endpoint is asynchronous, it just always returns ok if an objectId was provided. If there are any errors, they are posted to the Slack admin channel.

If a profile is found, it is posted to the Slack profile channel as a PNG image.

Setup

git clone git@github.com:ColumbiaRoad/impact-helper-api.git
cd impact-helper-api
cp .env.example .env

Configure the HubSpot integration

1. Log in to HubSpot.
2. Go to Settings -> Integrations -> Private Apps -> Create a private app.
3. Basic info tab: Add a name for your private app (and optionally a logo and description).
4. Scopes tab: Add the following scopes:

• crm.objects.companies.read
• crm.objects.deals.read

1. Click Create app -> Continue creating -> Go to app details.
2. In the Access token section, click Show token -> Copy.
3. In your .env file, paste the token as the value of HUBSPOT_ACCESS_TOKEN.

Configure the Upright integration

1. Log in to Upright.
2. On the top right, click your name -> Account.
3. Go to Administration.
4. Generate an API token, copy it and paste it as the .env value of UPRIGHT_API_TOKEN.

Configure the Slack integration

1. Create a new channel in Slack. This channel will be used for error messages. You can also use this channel for testing the bot during development.
2. Log in to api.slack.com/apps.
3. Click Create New App -> From scratch.
4. Add App Name and pick a workspace.
5. Create App.
6. Go to OAuth & Permissions.
7. Under Scopes -> Bot Token Scopes, click Add an OAuth Scope. Add the following scopes:

• files:write
• incoming-webhook

1. Scroll up and click Install to Workspace.
2. Under Where should post?, select the channel you created earlier.
3. Click Allow.
4. Copy the Bot User OAuth Token and paste it as the .env value of SLACK_TOKEN.
5. In Slack, go to the channel you created earlier. Click on the channel name at the top and scroll down.
6. Copy the Channel ID and paste it as the .env value of SLACK_ADMIN_CHANNEL.
7. Similarly, set SLACK_PROFILE_CHANNEL as the channel you want the impact profiles to be posted on (can be the same as SLACK_ADMIN_CHANNEL during development).

Local development and deployment

There are two ways to deploy and run this application:

Option 1: Traditional Node.js Server

Runs the app as a standard Hapi.js HTTP server — suitable for local dev or hosting on platforms like Heroku or EC2.

Build and run:

npm install
cp .env.example .env
npm run build
npm start

This starts the server locally on the port specified in .env (default 3000).

Ensure Redis and any external services are available if needed.

Option 2 (New): AWS Lambda Deployment (via AWS SAM)

This project supports running the API as an AWS Lambda function, managed using AWS SAM (Serverless Application Model).

Set the environment variable USE_AWS_LAMBDA=true to run in Lambda mode. When enabled, Redis and pino-pretty logging are disabled to ensure compatibility with the Lambda runtime.

Prerequisites

• An AWS account, AWS Identity and Access Management (IAM) credentials, IAM access key pair, and AWS Command Line Interface (AWS CLI) to configure AWS credentials. Note: In this project, AWS Account and IAM credentials are only required for GitHub Actions deployments. For local development and testing, it should be okay to skip this step as SAM CLI runs Lambda functions and API Gateway locally using Docker. However, if local SAM usage fails without credentials, follow the instructions from this step.
• Install AWS SAM CLI

Setup and Run Locally

npm install
cp .env.example .env
npm run start:local-sam

This command will:

1. Convert your .env file to env.json

2. Build the Lambda function with template.local.yaml

3. Start the API Gateway emulator locally

Test the health check endpoint:

curl http://localhost:3000/status
# Should output: ok

⚠️ Important: template.local.yaml is only used for local testing. It defines empty environment variables that get populated using env.json. ✅ Real production env variables must never be added to the template files and are configured directly in the AWS Lambda dashboard.

Testing API Routes locally with REST Client (VS Code)

To test the API routes with .rest files (requests/HS-companyDealTrigger.rest) in VS Code:

First, install the REST Client extension.

Then, define the hubspothash and dealshash like this in .vscode/settings.json:

{
  "rest-client.environmentVariables": {
    "$shared": {
      "hubspothash": "your-HUBSPOT_HASH",
      "dealshash": "your-DEALS_HASH"
    }
  }
}

Then follow the instructions from the HS-companyDealTrigger.rest files to test the different endpoints.

Deployment to AWS (via GitHub Actions)

This project uses GitHub Actions to deploy automatically to AWS Lambda on each push to the main branch.

(Note: The initial deployment to AWS should be done manually using the command sam build && sam deploy --guided. After the initial deployment, remember to add the environment variables for the Lambda function for example through the function's Configuration-settings in AWS Console. At this point, remember to also add the required Github Actions Secrets to Github for future deployments (listed below))

GitHub Actions Secrets Required For CI/CD

AWS_ACCESS_KEY_ID (required) (from IAM user) AWS_SECRET_ACCESS_KEY (required) (from IAM user) AWS_REGION (optional) (uses eu-north-1 by default) AWS_STACK_NAME (required) (should match your AWS Lambda function stack name)

New Build Output

When running sam build, a .aws-sam/ directory will be created to the root. This contains the generated deployment artifacts and should not be committed to git (already included in .gitignore).