Integration and API Spec

Integration and API Spec

Competitor Intelligence Tracking

Read-only data source providing the competitor list and monitored source URLs. Polled by the orchestration layer on every daily scan trigger at 6 AM.

// Input
spreadsheetId: GSHEETS_COMPETITOR_SHEET_ID  (from credential store)
range: 'CompetitorSources'
// Output
competitor_name: string
website_url: string
news_keywords: string
alert_feed_url: string
active: boolean

Primary intelligence database. The Intelligence Agent writes one record per qualifying signal. The Digest Agent reads the current week's records each Friday morning to compile the briefing.

// Input (write - Intelligence Agent)
database_id: NOTION_DATABASE_ID
Competitor: string  (must match existing select option)
Category: string  (Pricing | Product | Market Expansion | Messaging | Leadership | Review Signal)
Relevance Score: integer  (3-5, threshold-filtered)
Source URL: string
Signal Date: ISO8601 date
Summary: string  (max 1800 chars)
HubSpot Deal ID: string | null
// Output (read - Digest Agent)
Array of page objects filtered by Signal Date >= last Friday

CRM integration. When a logged signal matches a competitor tracked against one or more open deals, the orchestration layer appends a timestamped note to each matched deal record.

// Input (deal lookup)
filter: { propertyName: 'competitor_tracked', operator: 'CONTAINS_TOKEN', value: competitor_name }
filter: { propertyName: 'dealstage', operator: 'NOT_IN', value: ['closedwon','closedlost'] }
// Input (note creation)
properties.hs_note_body: '[COMPETITOR INTEL - {Signal Date}] {Category}: {Summary} | Source: {Source URL}'
associations: [{ to: { id: deal_id }, types: [{ associationCategory: 'HUBSPOT_DEFINED', associationTypeId: 214 }] }]
// Output
note_id: string
associated_deal_id: string

Digest delivery channel. The Digest Agent posts the formatted weekly competitive briefing to the designated sales Slack channel each Friday at 8 AM.

// Input
channel: SLACK_SALES_CHANNEL_ID
blocks: Block Kit JSON array
  - Header: 'Weekly Competitor Intel Brief - {YYYY-MM-DD}'
  - Section per competitor: bold name + signal bullet list
  - Context: Notion database URL
unfurl_links: false
// Output
ts: string  (message timestamp, stored for thread reply chaining if needed)

Optional digest email to the sales manager sent after the Slack post. Uses the same compiled digest content as the Slack message, formatted as HTML email.

// Input
to: GMAIL_MANAGER_RECIPIENT
from: GMAIL_SENDER_ADDRESS
subject: 'Competitor Intel Brief - Week of {Monday YYYY-MM-DD}'
body: HTML string (competitor groups, signal summaries, Notion link)
condition: GMAIL_DIGEST_ENABLED == true AND Slack post succeeded
// Output
message_id: string  (Gmail message ID for logging)

// Credential store manifest
// All entries are encrypted at rest in the orchestration platform.
// Never expose these values in workflow node UI, logs, or version control.

GSHEETS_SERVICE_ACCOUNT_KEY      // JSON key file (base64-encoded) for Google Sheets read access
GSHEETS_COMPETITOR_SHEET_ID      // Google Sheets spreadsheet ID (string)

NOTION_INTEGRATION_TOKEN         // Notion internal integration secret (secret_xxx...)
NOTION_DATABASE_ID               // Notion database ID (32-char hex string)
NOTION_DATABASE_URL              // Full public URL to Notion database view (for digest links)

HUBSPOT_PRIVATE_APP_TOKEN        // HubSpot private app Bearer token (pat-xxx...)
HUBSPOT_PORTAL_ID                // HubSpot portal/account ID (integer)

SLACK_BOT_TOKEN                  // Slack bot OAuth token (xoxb-xxx...)
SLACK_SALES_CHANNEL_ID           // Slack channel ID (C0XXXXXXXXX, not channel name)

GMAIL_OAUTH_TOKEN                // Gmail OAuth 2.0 refresh token for sending account
GMAIL_SENDER_ADDRESS             // Sending email address (string)
GMAIL_MANAGER_RECIPIENT          // Sales manager email address (string)
GMAIL_DIGEST_ENABLED             // Feature flag boolean: true | false

AI_API_KEY                       // API key for the AI language model provider
RELEVANCE_THRESHOLD              // Integer (default: 3); signals below this score are discarded

// Rotation policy: rotate all tokens every 90 days or immediately on suspected compromise.
// HubSpot private app tokens do not expire but must be rotated manually on staff offboarding.