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

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.

There are two endpoints:

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.

POST /dealPNG

This endpoint is similar to deals. However, this doesn't post the profile to Slack. Instead, it returns the PNG image as the response body.

If there are errors, the first error is included in the response body.

Setup

git clone [email protected]: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_ERROR_CHANNEL.
7. Similarly, set SLACK_CHANNEL as the channel you want the impact profiles to be posted on (can be the same as SLACK_ERROR_CHANNEL during development).

Deployment

Deploy the app and set the environment variables as instructed in .env.example. The build script is npm run build and the start script is npm start.