# GrowthPilot AI CRM Integration Runbook

This runbook turns GrowthPilot AI pilot leads into an authorized CRM, sheet, or automation destination. It is designed for Airtable, HubSpot, Google Sheets, Notion, Zapier, Make, or a custom webhook bridge.

## Goal

- Preserve each lead in GrowthPilot AI JSONL during MVP operations.
- Prefer sending every new lead to an authorized external system through `LEAD_WEBHOOK_URL`.
- If a CRM webhook is not available yet, mirror lead, event, and retry JSONL to mounted persistent storage through `LEAD_BACKUP_DIR`.
- Carry lead qualification context into follow-up: `lead.leadScore`, `lead.leadPriority`, `lead.nextAction`, and `lead.qualificationReasons`.
- Avoid fake CRM writes, fake outreach, or paid automation before account authorization.

## Environment Variables

```bash
LEAD_WEBHOOK_URL=https://your-automation-endpoint.example/webhook
LEAD_WEBHOOK_TOKEN=optional-shared-secret
LEAD_WEBHOOK_TIMEOUT_MS=10000
LEAD_WEBHOOK_RETRY_DELAY_MS=60000
LEAD_BACKUP_DIR=/mounted/persistent/lead-backup
```

If `LEAD_WEBHOOK_TOKEN` is set, GrowthPilot AI sends it as:

```http
Authorization: Bearer <LEAD_WEBHOOK_TOKEN>
```

Use `LEAD_BACKUP_DIR` only when the path is durable across deploys/restarts, such as a Docker named volume, VPS disk path, or provider-mounted volume. A temporary folder is not production CRM evidence.

## Minimum CRM Fields

| GrowthPilot field | CRM field suggestion | Why it matters |
|---|---|---|
| `source` | Integration source | Filter or tag records created by GrowthPilot AI. |
| `lead.id` | External lead id | Prevent duplicate imports. |
| `lead.createdAt` | Created date | Sort launch spikes and SLA windows. |
| `lead.businessName` | Company | Account or deal name. |
| `lead.contact` | Email/contact | Primary reply path. |
| `lead.productUrl` | Product/service URL | Audit target and qualification proof. |
| `lead.plan` | Offer requested | Segment free audit, pilot, and paid intent. |
| `lead.utmSource` | Source | Attribute Product Hunt, Reddit, LinkedIn, directories, or partner traffic. |
| `lead.utmCampaign` | Campaign | Track launch and content experiments. |
| `lead.leadScore` | Lead score | Prioritize follow-up. |
| `lead.leadPriority` | Priority | Route high, medium, and low intent. |
| `lead.nextAction` | Next action | Tell the operator what to do next. |
| `lead.qualificationReasons` | CRM notes | Preserve why the lead was scored. |

## Zapier Setup

1. Create a Zap with **Webhooks by Zapier** as the trigger.
2. Choose **Catch Hook** and copy the webhook URL into `LEAD_WEBHOOK_URL`.
3. Submit a test lead through `/offers/free-ai-growth-audit.html`.
4. Map fields into HubSpot, Airtable, Google Sheets, Gmail, Slack, or Notion.
5. Confirm nested `lead.leadScore`, `lead.leadPriority`, `lead.nextAction`, and `lead.qualificationReasons` are mapped, not discarded.

## Make Setup

1. Create a scenario with a **Custom webhook** module.
2. Copy the generated webhook URL into `LEAD_WEBHOOK_URL`.
3. Add routers for `leadPriority = high`, `medium`, and `low`.
4. Send high-priority leads to CRM plus Slack or email.
5. Send low-priority leads to a nurture sheet or Notion database.

## Airtable Setup

1. Create a base named `GrowthPilot Leads`.
2. Add fields for the minimum CRM fields above.
3. Use Airtable Automations, Zapier, or Make to receive the webhook payload.
4. Use `id` as the dedupe key.
5. Create views for high-priority leads and leads missing a reply.

## HubSpot Setup

1. Use Zapier, Make, or a private app bridge to receive the webhook.
2. Create or update a contact by `email`.
3. Create a deal for `leadPriority = high`.
4. Store `qualificationReasons` and `nextAction` as notes or custom properties.
5. Trigger a founder or sales task for high-priority leads.

## Retry Verification

1. Temporarily point `LEAD_WEBHOOK_URL` to an endpoint that returns `500`.
2. Submit a test lead.
3. Open `ops.html?token=<OPS_TOKEN>` and confirm the failed item appears in the webhook retry queue.
4. Fix the endpoint.
5. Press retry in the ops dashboard or call `POST /api/webhook-retry` with `x-ops-token`.
6. Confirm the CRM receives the lead and the queue is clean.

## Mounted Backup Verification

1. Set `LEAD_BACKUP_DIR` to a mounted persistent path, such as `/app/lead-backup` in Docker Compose or `/opt/growthpilot-ai/lead-backup` on the VPS kit.
2. Submit a test lead through `/offers/free-ai-growth-audit.html`.
3. Confirm the primary `data/leads.jsonl` file and backup `LEAD_BACKUP_DIR/leads.jsonl` contain the same test lead.
4. Submit an event or use a UTM landing page and confirm `events.jsonl` is mirrored.
5. If webhook retry is enabled and fails, confirm `lead-webhook-retry.jsonl` is mirrored and then cleared in both locations after a successful retry.

## Launch Boundary

This runbook is an operational handoff. It does not authorize real CRM writes, social posting, outreach, paid directories, or ad spend. Those actions require account access and explicit owner approval.

## Related Assets

- Public integration page: https://growthpilot.ai/integrations/
- Webhook payload schema: https://growthpilot.ai/integrations/webhook-payload.schema.json
- Lead qualification handoff: https://growthpilot.ai/ops/lead-qualification.html
- Free audit offer: https://growthpilot.ai/offers/free-ai-growth-audit.html
- AI discovery manifest: https://growthpilot.ai/ai-discovery.json