Developer Handover Pack

Developer Handover Pack

New Client Onboarding Handoff

Watches DocuSign for a fully executed contract event and immediately initiates the onboarding sequence. On receipt of the webhook payload, the agent parses client name, deal value, signer email, and document ID from the envelope data, then writes those values to the corresponding HubSpot deal record, advancing the deal stage to Closed Won and stamping the close date. This agent acts as the single source of truth handoff: nothing downstream fires until this agent confirms a clean HubSpot write. If the HubSpot deal cannot be located by the DocuSign envelope reference, the agent halts and posts an alert rather than continuing with incomplete data.

// Input
DocuSign envelope webhook payload {
  envelope_id: string,
  status: 'completed',
  signer_email: string,
  signer_name: string,
  completed_date_utc: ISO8601,
  document_name: string,
  custom_fields: { deal_value: number, hs_deal_id: string }
}

// Output
HubSpot deal record update {
  hs_deal_id: string,
  dealstage: 'closedwon',
  closedate: ISO8601,
  contract_value: number,
  docusign_envelope_id: string,
  onboarding_status: 'triggered'
}

Fires immediately after the Handoff Trigger Agent confirms the HubSpot deal is updated to Closed Won. This agent handles all digital workspace creation for the new client: it duplicates the master Google Drive folder template into the designated client accounts directory, names the folder using the pattern '[ClientName] - [CloseYear]', and shares it with the delivery lead's Google account. Simultaneously, it creates a new Notion page from the standard client onboarding template, populates all structured fields with HubSpot deal data, and embeds links to both the Google Drive folder and the signed contract PDF. The signed PDF is retrieved from DocuSign via the Envelopes:documents endpoint and uploaded directly to the new Drive folder. All three outputs (Drive folder URL, Notion page URL, signed PDF Drive link) are stored back on the HubSpot deal record for downstream agents to consume.

// Input
Internal trigger payload from Handoff Trigger Agent {
  hs_deal_id: string,
  client_name: string,
  signer_email: string,
  contract_value: number,
  closedate: ISO8601,
  docusign_envelope_id: string,
  delivery_lead_email: string    // pulled from HubSpot deal owner mapping
}

// Output
Google Drive {
  drive_folder_id: string,
  drive_folder_url: string,
  signed_pdf_file_id: string,
  signed_pdf_url: string
}
Notion {
  notion_page_id: string,
  notion_page_url: string
}
HubSpot deal update {
  hs_deal_id: string,
  drive_folder_url: string,       // written to custom property
  notion_page_url: string,        // written to custom property
  signed_pdf_url: string,         // written to custom property
  onboarding_status: 'workspace_ready'
}

Fires once the Workspace Provisioning Agent confirms both the Drive folder and Notion page are created, signalled by onboarding_status = 'workspace_ready' on the HubSpot deal record. The agent simultaneously dispatches two communications: an internal Slack handoff brief posted to the designated delivery channel, and an external client welcome email sent via Gmail. The Slack message is structured with the client name, contract value, key contact details, links to the Drive folder and Notion workspace, and a prompt for the delivery lead to assign team members. The Gmail welcome email is composed from a stored template, personalised with the client name, account manager name, and outlined next steps, and sent from the account manager's authenticated Gmail address. After both sends are confirmed, the agent writes a completion note to the HubSpot deal timeline, setting onboarding_status to 'handoff_complete'.

// Input
HubSpot deal record (polled or event-triggered) {
  hs_deal_id: string,
  client_name: string,
  signer_email: string,
  contract_value: number,
  closedate: ISO8601,
  account_manager_email: string,  // HubSpot deal owner email
  drive_folder_url: string,
  notion_page_url: string,
  signed_pdf_url: string,
  onboarding_status: 'workspace_ready'
}

// Output
Slack message to #delivery channel {
  channel: string,               // confirmed delivery channel name
  blocks: [
    header: 'New Client Handoff: [client_name]',
    fields: { contract_value, closedate, signer_email },
    links: { drive_folder_url, notion_page_url, signed_pdf_url },
    action_prompt: 'Please assign delivery team members'
  ]
}
Gmail message to client {
  from: account_manager_email,
  to: signer_email,
  subject: 'Welcome to [YourCompany.com] - Next Steps',
  body: personalised_template { client_name, account_manager_name, next_steps }
}
HubSpot deal timeline note {
  hs_deal_id: string,
  note: 'Onboarding handoff complete. Slack brief sent. Welcome email sent.',
  onboarding_status: 'handoff_complete'
}

// ═══════════════════════════════════════════════════════════════
// NEW CLIENT ONBOARDING HANDOFF: END-TO-END DATA FLOW
// Trigger to completion across three agents and six tools
// ═══════════════════════════════════════════════════════════════

// ── TRIGGER ─────────────────────────────────────────────────────
DocuSign.envelope.status == 'completed'
  → POST to automation_platform.inbound_webhook_url
  → payload {
      envelope_id: string,
      status: 'completed',
      signer_name: string,
      signer_email: string,
      completed_date_utc: ISO8601,
      custom_fields.hs_deal_id: string,
      custom_fields.deal_value: number
    }

// ── AGENT 1: HANDOFF TRIGGER AGENT ──────────────────────────────
// Receives DocuSign webhook, validates envelope, updates HubSpot

Step 1.1: Parse envelope payload
  envelope_id       = payload.envelope_id
  signer_email      = payload.signer_email
  signer_name       = payload.signer_name
  deal_value        = payload.custom_fields.deal_value
  hs_deal_id        = payload.custom_fields.hs_deal_id
  completed_date    = payload.completed_date_utc

Step 1.2: Validate HubSpot deal lookup
  HubSpot.GET /crm/v3/objects/deals/{hs_deal_id}
    → IF deal not found OR dealstage == 'closedwon':
        → log duplicate/error, POST Slack alert, HALT
    → ELSE: proceed

Step 1.3: Update HubSpot deal to Closed Won
  HubSpot.PATCH /crm/v3/objects/deals/{hs_deal_id}
    body {
      dealstage:              'closedwon',
      closedate:              completed_date,
      amount:                 deal_value,
      docusign_envelope_id:   envelope_id,
      onboarding_status:      'triggered'
    }
  → confirmed_deal_id = hs_deal_id

// ── AGENT 1 → AGENT 2 HANDOFF ───────────────────────────────────
// HubSpot onboarding_status = 'triggered' fires Workspace Provisioning Agent

// ── AGENT 2: WORKSPACE PROVISIONING AGENT ───────────────────────
// Creates Drive folder, Notion page, uploads signed PDF

Step 2.1: Pull full deal data from HubSpot
  HubSpot.GET /crm/v3/objects/deals/{confirmed_deal_id}
    → client_name          = deal.properties.dealname
    → signer_email         = deal.properties.signer_email
    → contract_value       = deal.properties.amount
    → closedate            = deal.properties.closedate
    → delivery_lead_email  = deal.properties.hubspot_owner_email
    → envelope_id          = deal.properties.docusign_envelope_id

Step 2.2: Copy Google Drive master template folder
  GoogleDrive.POST /drive/v3/files/{MASTER_TEMPLATE_FOLDER_ID}/copy
    body {
      name: sanitise('[client_name] - [YYYY]'),
      parents: [CLIENT_ACCOUNTS_PARENT_FOLDER_ID]
    }
  → drive_folder_id  = response.id
  → drive_folder_url = 'https://drive.google.com/drive/folders/' + drive_folder_id

Step 2.3: Share Drive folder with delivery lead
  GoogleDrive.POST /drive/v3/files/{drive_folder_id}/permissions
    body { type: 'user', role: 'writer', emailAddress: delivery_lead_email }

Step 2.4: Retrieve signed PDF from DocuSign
  DocuSign.GET /v2.1/accounts/{account_id}/envelopes/{envelope_id}/documents/combined
    → signed_pdf_bytes = response.binary
    → RETRY up to 3 times at 30s intervals on failure

Step 2.5: Upload signed PDF to Drive folder
  GoogleDrive.POST /upload/drive/v3/files
    metadata { name: '[client_name] - Signed Contract.pdf', parents: [drive_folder_id] }
    media: signed_pdf_bytes
  → signed_pdf_file_id = response.id
  → signed_pdf_url = 'https://drive.google.com/file/d/' + signed_pdf_file_id

Step 2.6: Create Notion client page from template
  Notion.POST /v1/pages
    body {
      parent: { database_id: NOTION_CLIENT_DB_ID },
      properties: {
        'Client Name':             { title: client_name },
        'Contract Value':          { number: contract_value },
        'Start Date':              { date: closedate },
        'Primary Contact Email':   { email: signer_email },
        'Drive Folder':            { url: drive_folder_url },
        'Signed Contract':         { url: signed_pdf_url }
      }
    }
  → notion_page_id  = response.id
  → notion_page_url = response.url

Step 2.7: Write asset URLs back to HubSpot deal
  HubSpot.PATCH /crm/v3/objects/deals/{hs_deal_id}
    body {
      drive_folder_url:   drive_folder_url,
      notion_page_url:    notion_page_url,
      signed_pdf_url:     signed_pdf_url,
      onboarding_status:  'workspace_ready'
    }

// ── AGENT 2 → AGENT 3 HANDOFF ───────────────────────────────────
// HubSpot onboarding_status = 'workspace_ready' fires Communications Agent

// ── AGENT 3: COMMUNICATIONS AGENT ───────────────────────────────
// Posts Slack brief and sends Gmail welcome email simultaneously

Step 3.1: Pull enriched deal data from HubSpot
  HubSpot.GET /crm/v3/objects/deals/{hs_deal_id}
    → client_name           = deal.properties.dealname
    → signer_email          = deal.properties.signer_email
    → contract_value        = deal.properties.amount
    → closedate             = deal.properties.closedate
    → account_manager_email = deal.properties.hubspot_owner_email
    → drive_folder_url      = deal.properties.drive_folder_url
    → notion_page_url       = deal.properties.notion_page_url
    → signed_pdf_url        = deal.properties.signed_pdf_url

Step 3.2: POST Slack handoff brief to delivery channel
  Slack.POST /api/chat.postMessage
    body {
      channel: DELIVERY_SLACK_CHANNEL_NAME,
      blocks: [
        header_block:  'New Client Handoff: [client_name]',
        section_block: { contract_value, closedate, signer_email },
        links_block:   { drive_folder_url, notion_page_url, signed_pdf_url },
        action_block:  'Please assign delivery team members'
      ]
    }
  → slack_ts = response.ts    // timestamp confirms delivery

Step 3.3: Send Gmail welcome email to client
  Gmail.POST /gmail/v1/users/{account_manager_email}/messages/send
    body {
      to:      signer_email,
      from:    account_manager_email,
      subject: 'Welcome to [YourCompany.com] - Next Steps',
      body:    render_template(welcome_email_template, {
                 client_name:          client_name,
                 account_manager_name: lookup_name(account_manager_email),
                 next_steps_text:      STATIC_NEXT_STEPS_STRING
               })
    }
  → gmail_message_id = response.id

Step 3.4: Log handoff completion on HubSpot deal timeline
  HubSpot.POST /crm/v3/objects/notes
    body {
      associations: [{ to: { id: hs_deal_id }, types: [{ associationTypeId: 214 }] }],
      properties: {
        hs_note_body: 'Onboarding handoff complete. Slack brief sent (ts: [slack_ts]). Welcome email sent (id: [gmail_message_id]).',
        hs_timestamp: now_utc
      }
    }

Step 3.5: Update HubSpot deal onboarding status
  HubSpot.PATCH /crm/v3/objects/deals/{hs_deal_id}
    body { onboarding_status: 'handoff_complete' }

// ── SEQUENCE COMPLETE ────────────────────────────────────────────
// Total automated elapsed time: < 3 minutes from DocuSign webhook receipt
// Remaining human steps: Step 6 (team assignment), Step 8 (kickoff scheduling)