Integration and API Spec

Integration and API Spec

Upsell and Cross-sell Triggers

Segment acts as the event source that initiates the entire workflow. A qualifying customer event (spend milestone, usage threshold, or renewal within 30 days) fires from Segment to the orchestration layer via a webhook destination. The orchestration layer validates the incoming payload signature before processing.

// Inbound webhook payload (key fields)
messageId       : string  // Segment-generated unique event ID; use for idempotency check
event           : string  // e.g. 'upsell_qualifying_event'
userId          : string  // Segment userId, maps to HubSpot contact lookup
properties.trigger_type    : string  // 'spend' | 'usage' | 'renewal'
properties.spend_total_usd : number  // cumulative spend to date
properties.usage_pct       : number  // usage as % of plan limit
properties.renewal_days    : number  // days until renewal
properties.account_tier    : string  // 'standard' | 'high_value'
timestamp       : ISO 8601 string
// Output to orchestration layer
Validated payload forwarded to HubSpot fetch step; messageId stored for dedup check

HubSpot is used in two distinct phases: first to fetch the full CRM contact and company record for the triggered customer (consumed by Agent 1), and second to log the outreach activity and offer details after the email is sent (executed by Agent 2). Both operations use the same OAuth 2.0 connection.

// Input to fetch step (from Segment payload)
userId or email  : string  // used to query contacts API
// GET /crm/v3/objects/contacts/{id}?properties=email,firstname,lastname,account_tier,
//   hs_external_id,hubspot_owner_id,hs_lead_status,lifecyclestage
// GET /crm/v3/objects/companies/{id}?properties=name,industry,annualrevenue,hs_num_associated_deals
// Output fields passed to Agent 1
contact.email, contact.firstname, contact.lastname, contact.account_tier,
contact.hubspot_owner_id, company.name, company.industry,
open_deals (count), last_activity_date
// Input to activity log step (from Agent 2)
contact_id, offer_name, offer_id, trigger_event, send_timestamp, send_status
// POST /crm/v3/timeline/events  (custom timeline event)
// PATCH /crm/v3/objects/contacts/{id}  (update hs_lead_status = 'Upsell Initiated')

Gmail is used by Agent 2 to either send the outreach email automatically (standard accounts) or to create a draft in the assigned sales rep's mailbox for manual review and approval (high-value accounts). Both paths use the same OAuth 2.0 connection scoped to the sending mailbox.

// Input to send step (from Agent 2)
to_email        : string  // customer email from HubSpot contact record
subject         : string  // generated by Agent 2 using offer_name + account context
body_html       : string  // personalised HTML body with placeholders resolved
from_address    : string  // value of GMAIL_SENDER_ADDRESS
reply_to        : string  // assigned rep email from hubspot_owner_id lookup
account_tier    : string  // 'standard' -> send | 'high_value' -> create draft
// POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send  (standard accounts)
// POST https://gmail.googleapis.com/gmail/v1/users/me/drafts         (high-value accounts)
// Output
message_id      : string  // Gmail message ID, stored in HubSpot activity log
thread_id       : string  // Gmail thread ID, stored for response monitoring
send_status     : 'sent' | 'draft_created' | 'failed'

Slack is used by Agent 2 to notify the assigned account owner immediately after an outreach email is sent or a draft is queued for review. The message includes the offer name, the customer name, and a direct link to the HubSpot contact record. A bot token is used for all Slack API calls.

// Input to Slack notification step
owner_email     : string  // from HubSpot hubspot_owner_id -> owner email lookup
customer_name   : string  // contact.firstname + contact.lastname
company_name    : string  // company.name
offer_name      : string  // from Agent 1 output
send_status     : string  // 'Sent automatically' | 'Awaiting your review'
hubspot_link    : string  // deep link to HubSpot contact record
// Runtime resolution
slack_user_id   : resolved via users.lookupByEmail(owner_email)
// POST https://slack.com/api/chat.postMessage
// Output
ts              : string  // Slack message timestamp, stored for audit log

Google Sheets serves two roles: as a read source for Agent 1 (the product offer catalogue and scoring rules) and as a write destination for the final outcome logging step (customer, offer, send date, account owner, send status). Both operations use the same OAuth 2.0 connection.

// Input: Agent 1 catalogue read
// GET https://sheets.googleapis.com/v4/spreadsheets/{GSHEETS_SPREADSHEET_ID}
//   /values/{GSHEETS_CATALOGUE_RANGE}
// Returns rows: offer_id, offer_name, offer_description, eligible_tiers,
//   min_spend_usd, min_usage_pct, priority_score
// Filtered against: contact.account_tier, spend_total_usd, usage_pct
// Input: outcome logging step (post-send)
row_data: [timestamp, customer_email, company_name, trigger_type,
           offer_name, send_status, account_owner_email, hubspot_link]
// POST https://sheets.googleapis.com/v4/spreadsheets/{GSHEETS_SPREADSHEET_ID}
//   /values/{GSHEETS_TRACKING_RANGE}:append?valueInputOption=USER_ENTERED
// Output
updatedRange : string  // confirmed appended range (e.g. 'OutcomeLog!A121:H121')

// Segment
SEGMENT_WEBHOOK_SECRET       : string  // HMAC-SHA256 shared secret from Segment webhook destination
SEGMENT_WRITE_KEY            : string  // Segment source write key (for reverse-lookup calls only)

// HubSpot
HUBSPOT_CLIENT_ID            : string  // OAuth app client ID
HUBSPOT_CLIENT_SECRET        : string  // OAuth app client secret
HUBSPOT_ACCESS_TOKEN         : string  // OAuth access token (auto-refreshed)
HUBSPOT_REFRESH_TOKEN        : string  // OAuth refresh token
HUBSPOT_PORTAL_ID            : string  // HubSpot account portal ID
HUBSPOT_TIMELINE_EVENT_TYPE_ID : string // Custom timeline event type ID
HUBSPOT_PIPELINE_STAGE_ID    : string  // Pipeline stage ID for 'Upsell Initiated'

// Gmail
GMAIL_CLIENT_ID              : string  // Google OAuth client ID
GMAIL_CLIENT_SECRET          : string  // Google OAuth client secret
GMAIL_ACCESS_TOKEN           : string  // OAuth access token (auto-refreshed)
GMAIL_REFRESH_TOKEN          : string  // OAuth refresh token
GMAIL_SENDER_ADDRESS         : string  // e.g. upsell-outreach@yourcompany.com
GMAIL_DRAFT_LABEL            : string  // e.g. 'FullSpec-Upsell-Review'
GMAIL_HIGH_VALUE_LABEL       : string  // e.g. 'FullSpec-HighValue-Sent'

// Slack
SLACK_BOT_TOKEN              : string  // Bot OAuth token (xoxb-...)
SLACK_FALLBACK_CHANNEL_ID    : string  // e.g. C0XXXXXXXXX (#sales-alerts channel ID)
SLACK_APP_ID                 : string  // Slack app ID for audit reference

// Google Sheets
GSHEETS_CLIENT_ID            : string  // Google OAuth client ID
GSHEETS_CLIENT_SECRET        : string  // Google OAuth client secret
GSHEETS_ACCESS_TOKEN         : string  // OAuth access token (auto-refreshed)
GSHEETS_REFRESH_TOKEN        : string  // OAuth refresh token
GSHEETS_SPREADSHEET_ID       : string  // Master spreadsheet ID
GSHEETS_CATALOGUE_RANGE      : string  // e.g. 'OfferCatalogue!A2:G'
GSHEETS_TRACKING_RANGE       : string  // e.g. 'OutcomeLog!A:H'
GSHEETS_DEDUP_RANGE          : string  // e.g. 'DedupLog!A:B'

// Orchestration rules
HIGHVALUE_THRESHOLD          : string  // Account tier value that triggers human review
CATALOGUE_CACHE_TTL_SECONDS  : number  // Max age of cached offer catalogue (max 3600)