Integration and API Spec

Integration and API Spec

Strategic Planning Workflow

Notion is the central repository for goal submission pages, the master strategy page, and weekly goal status updates. The automation reads from and writes to Notion databases and pages via the Notion REST API. All page and database IDs are stored in the credential store, never hardcoded.

// Input (Agent 1 - template duplication)
NOTION_SUBMISSION_TEMPLATE_PAGE_ID -> GET /pages/{id}
Department list (from credential store config) -> iterate
// Output (Agent 1 - template duplication)
POST /pages -> new submission page per department
  properties.Department = '{dept_name}'
  properties.Quarter = '{quarter_label}'
  properties.Status = 'Not Started'
// Input (Agent 1 - master consolidation)
GET /databases/{NOTION_GOAL_STATUS_DB_ID}/query -> all submission pages
// Output (Agent 1 - master consolidation)
PATCH /pages/{NOTION_MASTER_STRATEGY_DB_ID} -> append consolidated blocks
// Input (Agent 2 - progress read)
GET /databases/{NOTION_GOAL_STATUS_DB_ID}/query -> filter: Status != 'Not Started'
// Output (Agent 2 - progress report)
Completion percentages per department -> Slack payload

Google Sheets is the source of financial and KPI data pulled at the start of each planning cycle. The Planning Data Agent reads designated cells and named ranges from the master financial spreadsheet and writes summary values into the master Notion strategy page.

// Input
GSHEETS_SPREADSHEET_ID + GSHEETS_FINANCIAL_RANGE
GET /v4/spreadsheets/{id}/values/{range}
// Output (raw response example)
{
  'range': 'FinancialSummary!B2:B20',
  'values': [['142500'], ['38200'], ['19400'], ...]
}
// Mapped output to orchestration layer
financial.revenue    = values[0][0]  // cast to float
financial.pipeline   = values[1][0]  // cast to float
financial.expenses   = values[2][0]  // cast to float

HubSpot provides pipeline and revenue data at the start of each planning cycle. The Planning Data Agent queries the Deals API to retrieve aggregate pipeline value and deal stage counts, which are written into the master Notion strategy page alongside the Google Sheets financial data.

// Input
GET /crm/v3/objects/deals
  ?properties=dealname,amount,dealstage,closedate,pipeline
  &filterGroups[0].filters[0].propertyName=pipeline
  &filterGroups[0].filters[0].operator=EQ
  &filterGroups[0].filters[0].value={HUBSPOT_PIPELINE_ID}
  Authorization: Bearer {HUBSPOT_PRIVATE_APP_TOKEN}
// Output (mapped)
hubspot.pipeline_total   = sum(deal.amount for deal in results)
hubspot.open_deals       = count(deal where stage != 'Closed Won')
hubspot.closed_won_value = sum(deal.amount where stage == 'Closed Won')

Slack is the notification and reporting channel for all outbound communications in the workflow: cycle kickoff messages, submission deadline reminders, plan distribution, weekly progress update requests, and the compiled weekly progress report to the leadership channel. Both agents use Slack. All channel IDs and user IDs are stored in the credential store.

// Input (kickoff DM to department head)
POST /api/chat.postMessage
  channel: {dm_channel_id}
  text: 'Planning cycle kickoff - please complete your goals by {deadline}'
  blocks: [ Section block with Notion page link button ]
// Input (leadership channel progress report)
POST /api/chat.postMessage
  channel: {SLACK_LEADERSHIP_CHANNEL_ID}
  text: 'Weekly Planning Progress Report - Week {n} of Q{q}'
  blocks: [ Header, Section per dept with completion %, Divider, Footer ]
// Output (API response, success)
{ 'ok': true, 'channel': 'C0123456789', 'ts': '1715000000.000100' }
// Output (API response, failure)
{ 'ok': false, 'error': 'channel_not_found' }  // -> trigger retry / alert

// Credential store contents
// Group: Notion
NOTION_API_TOKEN                  = 'secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxx'
NOTION_MASTER_STRATEGY_DB_ID      = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
NOTION_SUBMISSION_TEMPLATE_PAGE_ID= 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
NOTION_GOAL_STATUS_DB_ID          = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
NOTION_APPROVAL_FLAG_PROP         = 'Plan Approved'

// Group: Google Sheets
GSHEETS_SERVICE_ACCOUNT_JSON      = '{ ...service account key JSON... }'
GSHEETS_SPREADSHEET_ID            = '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms'
GSHEETS_FINANCIAL_RANGE           = 'FinancialSummary!B2:B20'
GSHEETS_KPI_RANGE                 = 'KPITracker!C2:C15'

// Group: HubSpot
HUBSPOT_PRIVATE_APP_TOKEN         = 'pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
HUBSPOT_PIPELINE_ID               = '12345678'
HUBSPOT_DEAL_STAGE_IDS            = '{"Proposal Sent":"111","Negotiation":"222","Closed Won":"333"}'

// Group: Slack
SLACK_BOT_TOKEN                   = 'xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx'
SLACK_LEADERSHIP_CHANNEL_ID       = 'C0123456789'
SLACK_DEPT_HEAD_USER_IDS          = '{"Finance":"U0111111","Marketing":"U0222222","Operations":"U0333333"}'
SLACK_SIGNING_SECRET              = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'  // reserved for future webhook use

// Group: Cycle control
CYCLE_START_DATE                  = '2025-07-01'  // update each quarter
CYCLE_END_DATE                    = '2025-09-30'  // update each quarter
CYCLE_ACTIVE                      = 'true'        // set false between cycles
CYCLE_DEADLINE_DATE               = '2025-07-14'  // submission deadline
DEPT_LIST                         = '["Finance","Marketing","Operations","Product"]'

// Group: Build metadata
BUILD_ENV                         = 'production'  // 'sandbox' during testing
HUBSPOT_TOKEN_CREATED             = '2025-05-20'  // for rotation tracking