Integration and API Spec

Integration and API Spec

Customer Testimonial Collection

Used as the primary trigger source (deal stage change) and as the destination for CRM note creation and contact property updates. A private app token is preferred over legacy API keys. The token must be rotated every 365 days and stored in the credential store.

// Inbound trigger payload (deal stage change webhook)
{
  "objectId": "<deal_id>",
  "propertyName": "dealstage",
  "propertyValue": "<HUBSPOT_DEAL_STAGE_ID>",
  "changeSource": "CRM_UI",
  "eventId": "<event_id>",
  "subscriptionType": "deal.propertyChange"
}

// Secondary GET for contact personalisation
GET /crm/v3/contacts/{contactId}?properties=firstname,lastname,email,company,hs_deal_name

// Note creation (POST)
POST /crm/v3/objects/notes
{
  "properties": {
    "hs_note_body": "Testimonial request sent via automation. Template: [template_name]. Typeform link: [typeform_url]",
    "hs_timestamp": "<ISO8601_timestamp>"
  },
  "associations": [{ "to": { "id": "<contact_id>" }, "types": [{ "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 202 }] }]
}

Handles all outbound email delivery: the initial testimonial request, the day-7 follow-up, and the day-14 follow-up. Emails are sent from the authenticated marketing manager account using pre-approved templates stored in the credential store. The sequence halts automatically when a Typeform submission is received.

// Gmail send payload (Users.messages.send)
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
{
  "raw": "<base64url_encoded_RFC2822_message>"
}

// Decoded message headers (example: initial request)
From: {{GMAIL_FROM_ADDRESS}}
To: {{contact.email}}
Subject: A quick favour, {{contact.firstname}}
Content-Type: text/html; charset=UTF-8

// Template variable substitutions
{{contact.firstname}}    -> HubSpot contact firstname property
{{contact.company}}     -> HubSpot contact company property
{{deal.name}}           -> HubSpot deal hs_deal_name property
{{typeform.url}}        -> TYPEFORM_FORM_URL + ?hubspot_id={{contact.id}}

Provides the structured submission form that customers complete. The form captures the testimonial text, a permission checkbox, and the customer's name and role. A hidden field carries the HubSpot contact ID so the submission can be matched back to the correct contact record. Typeform fires a webhook to the orchestration layer on each submission.

// Inbound webhook payload from Typeform (form_response event)
{
  "event_id": "<uuid>",
  "event_type": "form_response",
  "form_response": {
    "form_id": "{{TYPEFORM_FORM_ID}}",
    "submitted_at": "<ISO8601_timestamp>",
    "hidden": { "hubspot_id": "<contact_id>" },
    "answers": [
      { "field": { "id": "tf_testimonial_text", "type": "long_text" }, "text": "<testimonial_text>" },
      { "field": { "id": "tf_permission",     "type": "yes_no"   }, "boolean": true },
      { "field": { "id": "tf_customer_name",  "type": "short_text"}, "text": "<name>" },
      { "field": { "id": "tf_customer_role",  "type": "short_text"}, "text": "<role>" }
    ]
  }
}

Receives formatted approval card messages from Agent 2 and delivers the marketing manager's Approve or Flag for Review decision back to the orchestration layer via Slack's interactivity endpoint. A custom Slack app must be created and installed into the workspace.

// Outbound approval card (chat.postMessage with Block Kit)
POST https://slack.com/api/chat.postMessage
{
  "channel": "{{SLACK_APPROVAL_CHANNEL_ID}}",
  "blocks": [
    { "type": "header", "text": { "type": "plain_text", "text": "New testimonial submission" } },
    { "type": "section", "fields": [
        { "type": "mrkdwn", "text": "*Customer:*\n{{tf_customer_name}}" },
        { "type": "mrkdwn", "text": "*Role:*\n{{tf_customer_role}}" }
    ]},
    { "type": "section", "text": { "type": "mrkdwn", "text": "*Testimonial:*\n{{tf_testimonial_text}}" }},
    { "type": "actions", "elements": [
        { "type": "button", "text": { "type": "plain_text", "text": "Approve" }, "style": "primary", "action_id": "testimonial_approve", "value": "{{submission_id}}" },
        { "type": "button", "text": { "type": "plain_text", "text": "Flag for Review" }, "style": "danger", "action_id": "testimonial_flag", "value": "{{submission_id}}" }
    ]}
  ]
}

// Inbound interaction payload (button click from manager)
{
  "type": "block_actions",
  "actions": [{ "action_id": "testimonial_approve", "value": "{{submission_id}}" }],
  "user": { "id": "<slack_user_id>", "name": "<username>" }
}

Serves as the testimonial library. Each approved submission is written as a new page in a dedicated Notion database. The database schema must be created and its ID stored in the credential store before build begins. The Notion integration token must be shared with the target database.

// Create page in testimonial database (POST)
POST https://api.notion.com/v1/pages
Authorization: Bearer {{NOTION_INTEGRATION_TOKEN}}
Notion-Version: 2022-06-28
{
  "parent": { "database_id": "{{NOTION_DATABASE_ID}}" },
  "properties": {
    "Customer Name":      { "title":     [{ "text": { "content": "{{tf_customer_name}}" } }] },
    "Role":               { "rich_text": [{ "text": { "content": "{{tf_customer_role}}" } }] },
    "Testimonial":        { "rich_text": [{ "text": { "content": "{{tf_testimonial_text}}" } }] },
    "Approved Date":      { "date":      { "start": "{{approved_at_iso8601}}" } },
    "HubSpot Contact ID": { "rich_text": [{ "text": { "content": "{{hubspot_contact_id}}" } }] },
    "Permission Granted": { "checkbox":  true },
    "Status":             { "select":    { "name": "Approved" } }
  }
}

# HubSpot
HUBSPOT_PRIVATE_APP_TOKEN=<hubspot_private_app_token>
HUBSPOT_PORTAL_ID=<hubspot_portal_id>
HUBSPOT_PIPELINE_ID=<pipeline_id>
HUBSPOT_DEAL_STAGE_ID=<closed_won_stage_internal_value>
HUBSPOT_WEBHOOK_SECRET=<hubspot_v3_signature_secret>

# Gmail / Google Workspace
GMAIL_CLIENT_ID=<google_oauth_client_id>
GMAIL_CLIENT_SECRET=<google_oauth_client_secret>
GMAIL_REFRESH_TOKEN=<google_oauth_refresh_token>
GMAIL_FROM_ADDRESS=marketing@[YourCompany.com]
GMAIL_TEMPLATE_INITIAL=<html_string_or_template_id>
GMAIL_TEMPLATE_FOLLOWUP_D7=<html_string_or_template_id>
GMAIL_TEMPLATE_FOLLOWUP_D14=<html_string_or_template_id>

# Typeform
TYPEFORM_PERSONAL_ACCESS_TOKEN=<typeform_pat>
TYPEFORM_FORM_ID=<form_id>
TYPEFORM_FORM_URL=https://[yourcompany].typeform.com/to/<form_id>
TYPEFORM_WEBHOOK_SECRET=<hmac_secret_set_at_webhook_registration>

# Slack
SLACK_BOT_TOKEN=xoxb-<slack_bot_token>
SLACK_SIGNING_SECRET=<slack_app_signing_secret>
SLACK_APPROVAL_CHANNEL_ID=<channel_id_not_channel_name>

# Notion
NOTION_INTEGRATION_TOKEN=secret_<notion_internal_token>
NOTION_DATABASE_ID=<testimonial_library_database_id>

# State store
STATE_STORE_TTL_DAYS=90