Plain to HubSpot Webhook Handler

Automatically creates HubSpot tickets when threads are created in Plain.

Quick Start

1. Install dependencies:

   bun install

2. Configure environment:

   cp .env.example .env
   # Edit .env with your API keys

3. Run the server:

   bun run index.ts

4. Set up webhook in Plain:

   • Go to Plain Settings → Webhooks
   • Add webhook URL: https://your-domain.com/plain/webhook
   • Subscribe to thread.thread_created events

Configuration

Copy .env.example to .env and fill in:

Variable	Description	Where to get it
PLAIN_API_KEY	Plain API key	Plain Settings → API Keys
HUBSPOT_ACCESS_TOKEN	HubSpot access token	HubSpot Developer
HUBSPOT_REFRESH_TOKEN	HubSpot refresh token	HubSpot OAuth flow
HUBSPOT_CLIENT_ID	HubSpot app client ID	HubSpot Developer
HUBSPOT_CLIENT_SECRET	HubSpot app client secret	HubSpot Developer

Prerequisites

• Bun runtime
• Plain workspace with API access
• HubSpot account with API access
• HubSpot app with scopes: tickets, crm.objects.companies.read

How It Works

1. Receives thread.thread_created webhook from Plain
2. Fetches thread details to get tenant ID
3. Fetches tenant details to get HubSpot company ID (externalId)
4. Creates HubSpot ticket associated with the company
5. Automatically refreshes HubSpot token if expired

Ticket Format:

• Subject: Thread title
• Content: {title}\n\n{description}\n\nSee in Plain: {threadUrl}
• Pipeline: 0, Stage: 1

Important: Tenant Mapping

Each Plain tenant must have its externalId set to the corresponding HubSpot company ID.

Example:

• Plain Tenant ID: te_01K65K8CH509YRN5HYEEH9DJHP
• Plain Tenant External ID: 244982408439
• HubSpot Company ID: 244982408439 ✓

Endpoints

• GET /health - Health check
• POST /plain/webhook - Webhook receiver

License

MIT