Integration and API Spec

Integration and API Spec

New Client Onboarding Handoff

DocuSign acts as the sole trigger source for the entire automation. The orchestration layer registers a Connect webhook listener on the DocuSign account. When an envelope reaches the 'completed' status (both parties have signed), DocuSign POSTs an XML or JSON payload to the registered listener URL. The automation must validate the HMAC-SHA256 signature on every inbound webhook before processing.

// Inbound webhook payload (abbreviated)
{
  "envelopeId": "a1b2c3d4-...",
  "status": "completed",
  "completedDateTime": "2024-06-10T09:14:32Z",
  "emailSubject": "Your contract with [YourCompany.com]",
  "customFields": {
    "client_name": "Acme Corp",
    "deal_value": "12000",
    "hubspot_deal_id": "hs_deal_88821",
    "account_manager_email": "rep@yourcompany.com",
    "scope_summary": "Brand strategy and web redesign"
  },
  "documents": [{ "documentId": "1", "name": "Signed Agreement" }]
}

HubSpot is both a data destination (deal stage update, audit log) and a data source (client and contact fields used by Agents 2 and 3). The automation uses the HubSpot Private App token model rather than OAuth App, as no end-user OAuth consent is required for server-to-server deal operations.

// PATCH /crm/v3/objects/deals/{dealId} — Agent 1 writes
{
  "properties": {
    "dealstage": "{HUBSPOT_CLOSED_WON_STAGE_ID}",
    "closedate": "2024-06-10",
    "contract_value": "12000",
    "scope_summary": "Brand strategy and web redesign",
    "account_manager_email": "rep@yourcompany.com",
    "hs_onboarding_status": "in_progress"
  }
}

// POST /crm/v3/objects/timeline/events — Agent 3 logs completion
{
  "objectType": "deals",
  "objectId": "hs_deal_88821",
  "eventTemplateId": "{HUBSPOT_ONBOARDING_EVENT_TEMPLATE_ID}",
  "tokens": { "status": "complete", "timestamp": "2024-06-10T09:17:45Z" }
}

Google Drive is used by Agent 2 to duplicate a master client folder template, rename it for the new client, upload the signed PDF from DocuSign, and share the folder with the delivery lead. A service account is used for folder operations so that no individual user's OAuth session is required for file manipulation.

// POST https://www.googleapis.com/drive/v3/files/{GDRIVE_TEMPLATE_FOLDER_ID}/copy
{ "name": "Acme Corp — Onboarding — 2024-06-10",
  "parents": ["{GDRIVE_CLIENTS_PARENT_FOLDER_ID}"] }

// POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart
// Uploads signed PDF to new folder

// POST https://www.googleapis.com/drive/v3/files/{newFolderId}/permissions
{ "role": "writer", "type": "user",
  "emailAddress": "{GDRIVE_DELIVERY_LEAD_EMAIL}" }

Notion is used by Agent 2 to create a new client workspace page by duplicating a template page within a designated Clients database. Deal data from HubSpot is used to populate database properties on the new page. The Notion internal integration token is used for all API calls.

// POST https://api.notion.com/v1/pages
{
  "parent": { "database_id": "{NOTION_CLIENTS_DATABASE_ID}" },
  "properties": {
    "Client Name": { "title": [{ "text": { "content": "Acme Corp" } }] },
    "Deal Value": { "number": 12000 },
    "Scope Summary": { "rich_text": [{ "text": { "content": "Brand strategy and web redesign" } }] },
    "Account Manager": { "email": "rep@yourcompany.com" },
    "Drive Folder URL": { "url": "https://drive.google.com/drive/folders/..." },
    "HubSpot Deal ID": { "rich_text": [{ "text": { "content": "hs_deal_88821" } }] },
    "Status": { "select": { "name": "Onboarding" } }
  }
}

Slack is used by Agent 3 to post a structured handoff brief to the internal delivery channel. The automation uses an incoming webhook URL for simplicity and reliability. If richer interactivity is needed in future (e.g. acknowledgement buttons), a full Slack Bot Token can be substituted.

// POST {SLACK_DELIVERY_WEBHOOK_URL}
{
  "blocks": [
    { "type": "header", "text": { "type": "plain_text", "text": "New Client Handoff: Acme Corp" } },
    { "type": "section", "fields": [
        { "type": "mrkdwn", "text": "*Scope:* Brand strategy and web redesign" },
        { "type": "mrkdwn", "text": "*Value:* $12,000" },
        { "type": "mrkdwn", "text": "*Account Manager:* rep@yourcompany.com" }
    ]},
    { "type": "section", "text": { "type": "mrkdwn",
      "text": "<{notion_url}|Notion Workspace>  |  <{drive_url}|Google Drive Folder>" } }
  ]
}

Gmail is used by Agent 3 to send a personalised welcome email to the new client from the account manager's address. Because the email must appear to come from a named individual rather than a shared inbox, OAuth 2.0 must be authorised per account manager. If multiple account managers send welcome emails, each must complete the OAuth consent flow and their refresh token must be stored separately.

// POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
// Authorization: Bearer {GMAIL_OAUTH_TOKEN_{MANAGER_ID}}
{
  "raw": "<base64url-encoded RFC 2822 message>"
}

// Decoded message headers:
// From: Alex Smith <rep@yourcompany.com>
// To: contact@acmecorp.com
// Subject: Welcome to [YourCompany.com], Acme Corp
// Content-Type: text/html; charset=UTF-8

// Body substitutions applied before encoding:
// {{client_name}}           -> Acme Corp
// {{account_manager_name}}  -> Alex Smith
// {{scope_summary}}         -> Brand strategy and web redesign
// {{notion_url}}            -> https://notion.so/...
// {{kickoff_scheduling_link}} -> https://calendly.com/...

// Credential store contents — all values stored by key name, never hardcoded

// DocuSign
DOCUSIGN_CLIENT_ID              = "<OAuth App Client ID>"
DOCUSIGN_CLIENT_SECRET          = "<OAuth App Client Secret>"
DOCUSIGN_ACCOUNT_ID             = "<DocuSign Account GUID>"
DOCUSIGN_HMAC_SECRET            = "<Connect HMAC shared secret>"
DOCUSIGN_WEBHOOK_URL            = "<Orchestration layer inbound endpoint>"
DOCUSIGN_BASE_URL               = "https://na4.docusign.net/restapi"

// HubSpot
HUBSPOT_PRIVATE_APP_TOKEN       = "<Private App Bearer Token>"
HUBSPOT_CLOSED_WON_STAGE_ID     = "<Pipeline stage ID string>"
HUBSPOT_ONBOARDING_EVENT_TEMPLATE_ID = "<Timeline event template ID>"

// Google Drive
GDRIVE_SERVICE_ACCOUNT_EMAIL    = "automation@yourcompany.iam.gserviceaccount.com"
GDRIVE_SERVICE_ACCOUNT_KEY_PATH = "/secrets/gdrive-service-account.json"
GDRIVE_TEMPLATE_FOLDER_ID       = "<Master template folder ID>"
GDRIVE_CLIENTS_PARENT_FOLDER_ID = "<Parent Clients folder ID>"
GDRIVE_DELIVERY_LEAD_EMAIL      = "<Delivery lead Google Workspace email>"

// Notion
NOTION_INTEGRATION_TOKEN        = "<Internal Integration Secret>"
NOTION_CLIENTS_DATABASE_ID      = "<Notion database ID>"
NOTION_CLIENT_TEMPLATE_PAGE_ID  = "<Template page ID>"

// Slack
SLACK_DELIVERY_WEBHOOK_URL      = "https://hooks.slack.com/services/..."
SLACK_DELIVERY_CHANNEL_ID       = "<Channel ID e.g. C0123456789>"
SLACK_ERROR_WEBHOOK_URL         = "https://hooks.slack.com/services/..."

// Gmail (one entry per account manager)
GMAIL_CLIENT_ID                 = "<Google OAuth App Client ID>"
GMAIL_CLIENT_SECRET             = "<Google OAuth App Client Secret>"
GMAIL_OAUTH_TOKEN_{MANAGER_ID}  = "<Stored access + refresh token JSON per sender>"
GMAIL_SENDER_NAME_{MANAGER_ID}  = "<Display name e.g. Alex Smith>"
GMAIL_WELCOME_TEMPLATE          = "<Named template ID in orchestration layer>"
GMAIL_SUBJECT_TEMPLATE          = "Welcome to [YourCompany.com], {{client_name}}"