HubSpot AWS Integration

General
1

HubSpot AWS Integration

HubSpot is an all-in-one CRM platform that helps businesses attract visitors, convert leads, and close customers through integrated marketing, sales, service, and content management tools. It empowers organizations to streamline operations, build meaningful customer relationships, and drive sustainable growth through data-driven insights and automation.

Table of Contents

Overview

This integration enables real-time data synchronization between HubSpot and your application through AWS Lambda and API Gateway. When events occur in HubSpot (such as contact creation), webhooks trigger Lambda functions to process these events and update your application accordingly.

Architecture

                  ┌───────────────┐
                  │               │
                  │   HubSpot     │
                  │               │
                  └───────┬───────┘
                          │
                          │ Webhook Event
                          ▼
┌───────────────┐  ┌───────────────┐  ┌───────────────┐
│               │  │               │  │               │
│ API Gateway   │━━│ Lambda        │━━│ Your          │
│ + Security    │  │ Function      │  │ Application   │
│               │  │               │  │               │
└───────────────┘  └───────────────┘  └───────────────┘

Features

  • Real-time event processing from HubSpot
  • Contact creation/update synchronization
  • Secure webhook handling with signature validation
  • Automatic retrieval of complete contact details
  • Custom field mapping between HubSpot and your application
  • Comprehensive security implementation

Prerequisites

  • AWS Account with access to:
    • Lambda
    • API Gateway
    • CloudWatch
  • HubSpot account with super admin access

Setup Instructions

AWS Setup

1. Create Lambda Function

  1. Open the AWS Management Console and navigate to Lambda
  2. Click “Create function”
  3. Select “Author from scratch”
  4. Enter function name (e.g., hubspot-webhook-handler)
  5. Select Node.js runtime (14.x or later)
  6. Create a new role with basic Lambda permissions
  7. Click “Create function”
  8. Upload the Lambda code from this repository or copy the code below:
// See the lambda-function.js file in this repository
exports.handler = async (event) => {
    try {
        console.log('Received event:', JSON.stringify(event, null, 2))

        // Parse the body if it's a string
        const body = typeof event.body === 'string' ? JSON.parse(event.body) : event.body

        // HubSpot sends an array of events
        const events = Array.isArray(body) ? body : [body]

        // Use Promise.all with array methods instead of for...of loop
        await Promise.all(events.map(async (hubspotEvent) => {
            console.log('Processing event:', JSON.stringify(hubspotEvent, null, 2))

            // Check if this is a contact creation event and route the request based on event
            if (hubspotEvent.subscriptionType === 'contact.creation') {
                // Get the contact ID from the event
                const contactId = hubspotEvent.objectId

                // Fetch the complete contact details from HubSpot
                const contactDetails = await getContactDetails(contactId)
                
                console.log(contactDetails)
                // Process the contact details (e.g., add to your application)
                await processContactInApplication(contactDetails)
            }
        }))

        // Return a successful response to HubSpot
        return {
            statusCode: 200,
            body: JSON.stringify({ message: 'Event processed successfully' }),
        }
    } catch (error) {
        console.error('Error processing webhook:', error)
        return {
            statusCode: 500,
            body: JSON.stringify({ message: 'Error processing webhook', error: error.message }),
        }
    }
}

2. Set Up Environment Variables

In your Lambda function, configure these environment variables:

  • HUBSPOT_API_KEY: Your HubSpot API key/access token
  • HUBSPOT_CLIENT_SECRET: For webhook signature validation
  • WEBHOOK_SECRET_TOKEN: Custom secret token for additional security

3. Configure API Gateway

  1. Create a new REST API
  2. Create a resource (e.g., /hubspot-webhooks)
  3. Add a POST method with Lambda integration
  4. Deploy the API to a stage (e.g., “prod”)
  5. Note the invoke URL - you’ll need this for HubSpot
    handler: handlers/hubspot_webhook.handler
    runtime: nodejs18.x
    layers:
      - ${ssm:NODE_LAYER}
    events:
      - http:
          path: /webhook
          method: post
          cors: true

HubSpot Setup

1. Create Private App for API Access

  1. Go to HubSpot > Settings > Integrations > Private Apps
  2. Click “Create private app”
  3. Name your app (e.g., “Contact Sync Integration”)
  4. Request scopes:
    • crm.objects.contacts.read
    • crm.objects.contacts.write (if needed)
  5. Create app and copy the access token

2. Configure Webhook Subscription

  1. Go to HubSpot > Settings > Integrations > Webhooks
  2. Click “Create webhook”
  3. Enter your API Gateway endpoint URL
  4. Select events to subscribe to (e.g., “contact.creation”)
  5. Set throttling rate if needed
  6. Save the webhook

3. Test the Integration

  1. Create a new contact in HubSpot
  2. Check CloudWatch logs to verify the webhook was received
  3. Confirm that the contact data was processed correctly

Security Implementation

  1. Add the security code from this repository to your Lambda function
  2. Configure shared secret in both HubSpot (if supported) and Lambda
  3. Update API Gateway resource policy for IP restrictions

Customizing HubSpot Forms

Adding Custom Fields

  1. Go to HubSpot > Settings > Properties under Data Management
  2. Click “Create property”
  3. Configure the property details:
    • Group: Choose or create new group
    • Label: What users will see
    • Field type: Text, dropdown, date, etc.

Making Fields Required

  1. Edit your form in HubSpot
  2. Click on the field you want to make required
  3. Toggle the “Required” switch to ON
  4. Save your form

Auto-filling User Emails

For forms that need to capture the current user’s email:

  1. Enable “Pre-populate fields with known values” in form settings
  2. Use HubSpot’s owner property for internal tracking
  3. For more advanced scenarios, implement custom JavaScript with HubSpot’s forms API

Troubleshooting

Common Issues

  1. Webhook not triggering Lambda

    • Check API Gateway configuration
    • Verify HubSpot webhook setup
    • Check CloudWatch logs for errors

  2. Missing contact data

    • Verify HubSpot API key permissions
    • Check property names in the API request
    • Look for API rate limiting issues

Resources

HubSpot Resources

4 Likes