Zapier Integration Guide

Quick answer: Automate Surmado reports with Zapier. Point a Surmado webhook_url at a Zapier Catch Hook trigger — Zapier receives the completion payload (with summary metrics already extracted) and forwards it to Google Sheets / Slack / Notion / email. For deeper data, follow up with a REST API fetch using your API key. Five common workflows included: quarterly tracking, competitive alerts, Notion dashboards, Strategy digests, multi-client agency reporting.

Reading time: 18 minutes

In this guide:

• Build quarterly tracking automation by catching Surmado’s report.completed webhook, reading report.summary.presence_score and related fields, and appending a row to Google Sheets (3 Zapier tasks per job)
• Create competitive alerts for weak positioning with Filter by Zapier on report.summary.competitive_rank, then posting to Slack only when rank > 3 (4 tasks when triggered)
• Set up Notion database integration for Site Audit reports using report.summary.seo_score, performance_score, accessibility_score, and critical_issues_count plus the quick_wins object (4 tasks per job)
• Send Strategy completion digests to leadership — Strategy webhooks don’t include a summary, but you get report.pdf_url (a 30-day magic link) which you can embed directly in an email (3 tasks per job)
• Build multi-client agency dashboard populating a master Google Sheet with all clients’ metrics using report.summary.business_name from the payload as the client filter (3-4 tasks per client report)

Cost: Zapier Starter plan ($20/month) supports these workflows.

---

Prerequisites

What You Need

1. Zapier account (Starter plan minimum for multi-step Zaps)
2. Surmado account with API access (Pro or Portfolio plan)
3. A Surmado API key (sur_live_...) — create at app.surmado.com under Settings → API Keys
4. Destination app account (Google Sheets, Slack, Notion, etc.)

Zapier Plan Requirements

Free plan:

• 100 tasks/month
• Single-step Zaps only
• Not sufficient for Surmado workflows (need multi-step)

Starter plan ($20/month):

• 750 tasks/month
• Multi-step Zaps (required)
• Recommended minimum

Professional plan ($50/month):

• Unlimited Zaps
• Paths (conditional logic)
• Recommended for agencies with multiple clients

---

The Integration Pattern

All five workflows below use the same shape:

1. Trigger: Webhooks by Zapier — “Catch Hook”. Zapier gives you a unique URL.
2. Configure Surmado to POST report completions to that URL by including webhook_url when creating the report.
3. Parse the incoming payload. Zapier flattens nested JSON with __ (double underscore) — so report.summary.presence_score becomes report__summary__presence_score in Zapier’s field picker.
4. (Optional) REST API fetch if you need fields beyond the summary. Call GET https://api.surmado.com/v1/reports/{{report__id}} with header Authorization: Bearer sur_live_YOUR_KEY.
5. Act — write to Google Sheets, post to Slack, create a Notion page, etc.

Example webhook payload

{
  "event": "report.completed",
  "timestamp": "2026-04-15T12:00:00+00:00",
  "report": {
    "id": "rpt_abc123xyz",
    "token": "SIG-2026-04-A1B2C",
    "product": "signal",
    "status": "completed",
    "tier": "basic",
    "data_url": "https://api.surmado.com/v1/reports/rpt_abc123xyz",
    "pdf_url": "https://api.surmado.com/v1/reports/view/VIEW_TOKEN",
    "summary": {
      "business_name": "Acme Coffee Roasters",
      "industry": "Food & Beverage",
      "brand_url": "https://acme.com",
      "presence_score": 34.2,
      "authority_score": 42.7,
      "competitive_rank": 4,
      "top_competitor": "Blue Bottle",
      "insights_summary": ["Presence score: 34.2 (↑5.5)", "..."]
    }
  }
}

Strategy reports ("product": "solutions") arrive without a summary object — use report.pdf_url and report.token instead.

---

Workflow 1: Quarterly Tracking to Google Sheets

Quarterly Tracking Use Case

Every time an AI Visibility report completes, add the summary metrics to a Google Sheet for time-series tracking.

Quarterly Tracking Setup

Step 1: Create Google Sheet

Sheet name: AI Visibility Tracking

Columns:

• A: Date
• B: Token
• C: Business Name
• D: Presence Score
• E: Authority Score
• F: Competitive Rank
• G: Top Competitor

---

Step 2: Create the Zap — Catch Hook Trigger

Trigger: Webhooks by Zapier → Catch Hook

Zapier gives you a URL like https://hooks.zapier.com/hooks/catch/12345/abcdef/. Copy it.

---

Step 3: Configure Surmado to Send the Webhook

When creating an AI Visibility report via the API, include webhook_url:

curl -X POST https://api.surmado.com/v1/reports/signal \
  -H "Authorization: Bearer sur_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_slug": "acme_corp",
    "url": "https://acme.com",
    "email": "founder@acme.com",
    "industry": "B2B SaaS",
    "location": "United States",
    "persona": "Small business owners",
    "pain_points": "Losing track of customer conversations",
    "brand_details": "Simple CRM with email integration",
    "direct_competitors": "HubSpot, Pipedrive",
    "webhook_url": "https://hooks.zapier.com/hooks/catch/12345/abcdef/"
  }'

Trigger one report so Zapier can capture a sample payload. (You can also use webhook.site first to preview the shape before wiring up Zapier.)

---

Step 4: Filter — Only Process Completed AI Visibility Reports

Action: Filter by Zapier

Conditions (all must match):

• event Exactly matches report.completed
• report__product Exactly matches signal

---

Step 5: Add to Google Sheets

Action: Google Sheets → Create Spreadsheet Row

Column mapping:

• Date: {{timestamp}}
• Token: {{report__token}}
• Business Name: {{report__summary__business_name}}
• Presence Score: {{report__summary__presence_score}}
• Authority Score: {{report__summary__authority_score}}
• Competitive Rank: {{report__summary__competitive_rank}}
• Top Competitor: {{report__summary__top_competitor}}

---

Step 6: Test and Enable

Test: Trigger a real AI Visibility report with the webhook URL. Confirm the row appears.

Enable: Turn on the Zap.

---

Quarterly Tracking Workflow Summary

1. Webhooks by Zapier: Catch Hook (Surmado POSTs report.completed)
   ↓
2. Filter: event = report.completed, product = signal
   ↓
3. Google Sheets: Create row with summary metrics

Zapier tasks per job: 3 tasks.

---

Workflow 2: Competitive Alerts to Slack

Competitive Alerts Use Case

When an AI Visibility report shows you ranked below #3, post a Slack alert.

Competitive Alerts Setup

Steps 1-3: Same as Workflow 1

(Catch Hook → configure webhook_url on reports → capture sample payload)

---

Step 4: Filter — Only Alert When Rank > 3

Action: Filter by Zapier

Conditions (all must match):

• event Exactly matches report.completed
• report__product Exactly matches signal
• report__summary__competitive_rank (Number) Greater than 3

---

Step 5: Send Slack Message

Action: Slack → Send Channel Message

Channel: #marketing (or your team’s channel)

Message:

:warning: Competitive rank alert for *{{report__summary__business_name}}*

Ranked *#{{report__summary__competitive_rank}}* in AI visibility.

*Presence score*: {{report__summary__presence_score}}
*Authority score*: {{report__summary__authority_score}}
*Top competitor*: {{report__summary__top_competitor}}

View full report: {{report__pdf_url}}
Report token: `{{report__token}}`

---

Competitive Alerts Workflow Summary

1. Catch Hook
   ↓
2. Filter: product = signal AND competitive_rank > 3
   ↓
3. Slack: Alert with metrics + PDF link

Zapier tasks when triggered: 4 tasks (filter counts as a task).

---

Workflow 3: Site Audit Results to Notion Database

Site Audit Use Case

Create a Notion database page for every completed Site Audit report with scores and the top quick wins.

Site Audit Setup

Step 1: Create Notion Database

Database name: Site Audit Reports

Properties:

• Title (Title): [Brand] - [Date]
• Token (Text): Intelligence Token
• SEO Score (Number): 0-100
• Performance Score (Number): 0-100
• Accessibility Score (Number): 0-100
• Total Pages (Number)
• Critical Issues (Number)
• Report Date (Date)
• PDF (URL)

---

Steps 2-3: Same Catch Hook Setup

Create a Catch Hook, then configure Site Audit reports to POST to that URL:

curl -X POST https://api.surmado.com/v1/reports/scan \
  -H "Authorization: Bearer sur_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_slug": "acme_corp",
    "url": "https://www.acme.com",
    "email": "founder@acme.com",
    "webhook_url": "https://hooks.zapier.com/hooks/catch/12345/abcdef/"
  }'

---

Step 4: Filter — Only Process Completed Site Audits

Conditions:

• event Exactly matches report.completed
• report__product Exactly matches scan

---

Step 5: Format Quick Wins with Code by Zapier

Action: Code by Zapier → Run Python

Input Data:

• quick_wins: {{report__summary__quick_wins}} (passes the object as JSON)

Code:

import json

raw = input_data.get('quick_wins', '{}')
try:
    quick_wins = json.loads(raw) if isinstance(raw, str) else (raw or {})
except Exception:
    quick_wins = {}

lines = [f"- **{area.replace('_', ' ').title()}**: {text}"
         for area, text in quick_wins.items() if text]

output = {'quick_wins_md': '\n'.join(lines) if lines else 'No quick wins surfaced.'}

---

Step 6: Create Notion Page

Action: Notion → Create Database Item

Database: Site Audit Reports

Property mapping:

• Title: {{report__summary__business_name}} - {{timestamp}}
• Token: {{report__token}}
• SEO Score: {{report__summary__seo_score}}
• Performance Score: {{report__summary__performance_score}}
• Accessibility Score: {{report__summary__accessibility_score}}
• Total Pages: {{report__summary__total_pages}}
• Critical Issues: {{report__summary__critical_issues_count}}
• Report Date: {{timestamp}}
• PDF: {{report__pdf_url}}

Page content:

## Quick Wins

{{quick_wins_md}}

## Executive Summaries

**Pages**: {{report__summary__page_analysis_summary}}

**Links**: {{report__summary__link_analysis_summary}}

**Schema**: {{report__summary__schema_strategy_summary}}

**Content gaps**: {{report__summary__content_gaps_summary}}

## Intelligence Token

`{{report__token}}`

Fetch full data: `GET https://api.surmado.com/v1/reports/{{report__id}}` with Bearer auth.

---

Site Audit Workflow Summary

1. Catch Hook
   ↓
2. Filter: product = scan
   ↓
3. Code by Zapier: Format quick_wins object into Markdown
   ↓
4. Notion: Create database page with scores + quick wins

Zapier tasks per job: 4 tasks.

---

Workflow 4: Strategy Completion Digest

Strategy Digest Use Case

When a Strategy report is delivered, send an email to leadership with the PDF link.

Note on Strategy Webhooks

Strategy ("product": "solutions") webhooks do not include a summary object — the Strategy report’s structured output is not currently exposed via the REST API. What you get is: report.id, report.token, report.pdf_url, and report.data_url. Use the PDF link in your digest.

Strategy Digest Setup

Steps 1-3: Same Catch Hook Setup

Create Strategy reports with a webhook_url:

curl -X POST https://api.surmado.com/v1/reports/solutions \
  -H "Authorization: Bearer sur_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_slug": "acme_corp",
    "email": "founder@acme.com",
    "business_story": "B2B SaaS CRM, 50 employees, $3M ARR",
    "decision": "Should we build a mobile app or improve the web experience?",
    "success": "40% engagement increase in 6 months",
    "timeline": "Need decision in next 30 days",
    "scale_indicator": "regional",
    "webhook_url": "https://hooks.zapier.com/hooks/catch/12345/abcdef/"
  }'

---

Step 4: Filter — Only Completed Strategy Reports

Conditions:

• event Exactly matches report.completed
• report__product Exactly matches solutions

---

Step 5: Send Email via Gmail

Action: Gmail → Send Email

To: leadership@yourcompany.com

Subject: Strategy report ready — token {{report__token}}

Body Type: HTML

Body:

<p>A Strategy report has been delivered.</p>

<p><strong>Token:</strong> <code>{{report__token}}</code></p>

<p><a href="{{report__pdf_url}}">View the full report (PDF)</a></p>

<p><small>The PDF link is a magic-link URL valid for approximately 30 days.
For programmatic access to the report metadata, call
<code>GET https://api.surmado.com/v1/reports/{{report__id}}</code>
with your Surmado API key.</small></p>

---

Strategy Digest Workflow Summary

1. Catch Hook
   ↓
2. Filter: product = solutions
   ↓
3. Gmail: Send PDF link to leadership

Zapier tasks per job: 3 tasks.

---

Workflow 5: Multi-Client Agency Dashboard

Agency Dashboard Use Case

Agency running AI Visibility for 20 clients monthly. Populate a master Google Sheet with every client’s metrics automatically.

Agency Dashboard Setup

Step 1: Create Master Sheet

Sheet name: Client Dashboard

Columns:

• A: Client Name
• B: Date
• C: Token
• D: Presence Score
• E: Authority Score
• F: Competitive Rank
• G: Top Competitor
• H: Status

---

Step 2: One Catch Hook for All Clients

Create a single Catch Hook Zap. Use the same webhook_url on every client’s reports. Because the payload includes report.summary.business_name (from the brand you registered), Zapier can route by client inside the same Zap.

Create each client as a separate brand once:

curl -X POST https://api.surmado.com/v1/brands/ensure \
  -H "Authorization: Bearer sur_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brand_name": "Phoenix Cool Air"}'

Then reuse the returned brand_slug when creating reports.

---

Step 3: Filter on report.completed and signal

(Same as Workflow 1.)

---

Step 4: Calculate Status with Formatter

Action: Formatter by Zapier → Numbers → Lookup Table

Input: {{report__summary__presence_score}}

Lookup:

• 0 to 30: At Risk
• 30.01 to 60: Needs Work
• 60.01 to 100: Leading

Output: Status text.

---

Step 5: Add to Master Sheet

Action: Google Sheets → Create Spreadsheet Row

Column mapping:

• Client Name: {{report__summary__business_name}}
• Date: {{timestamp}}
• Token: {{report__token}}
• Presence Score: {{report__summary__presence_score}}
• Authority Score: {{report__summary__authority_score}}
• Competitive Rank: {{report__summary__competitive_rank}}
• Top Competitor: {{report__summary__top_competitor}}
• Status: (from Step 4)

---

Step 6: Conditional Slack Alert for At-Risk Clients

Action: Filter by Zapier

Condition: report__summary__presence_score (Number) Less than 30

Action: Slack → Send Channel Message

Message:

:rotating_light: At-risk client alert: *{{report__summary__business_name}}*

*Presence score*: {{report__summary__presence_score}} (below 30 threshold)
*Competitive rank*: #{{report__summary__competitive_rank}}

Action needed: Schedule a Strategy report or content optimization sprint.

View AI Visibility report: {{report__pdf_url}}

---

Agency Dashboard Workflow Summary

1. Catch Hook (single URL, used by all client reports)
   ↓
2. Filter: product = signal
   ↓
3. Formatter: Classify status from presence score
   ↓
4. Google Sheets: Add row with client metrics
   ↓
5. [If presence_score < 30] Slack: at-risk alert

Zapier tasks per client report: 3-4 tasks. For 20 clients/month: ~70-90 tasks total (well within Starter plan).

---

Advanced Patterns

Pattern 1: Fetch Deeper Data via REST API

The webhook summary covers most needs, but if you want platform-specific breakdowns (e.g. ChatGPT vs Claude presence scores), fetch the full public_intelligence object:

Action: Webhooks by Zapier → GET

URL: https://api.surmado.com/v1/reports/{{report__id}}

Headers:

• Authorization: Bearer sur_live_YOUR_API_KEY

Response shape (AI Visibility):

{
  "report_id": "rpt_abc123xyz",
  "status": "completed",
  "token": "SIG-2026-04-A1B2C",
  "public_intelligence": {
    "summary": { "presence_score": 34.2, "...": "..." },
    "data": {
      "visibility_metrics": { "presence_score": 34.2, "ghost_influence_percentage": 48.3 },
      "platform_variance": { "chatgpt": { "presence_score": 42.1 }, "claude": { "..." } },
      "competitive_position": { "rank": 4, "total_competitors": 12 },
      "...": "..."
    }
  }
}

In Zapier, these flatten to public_intelligence__data__platform_variance__chatgpt__presence_score, etc.

See Structured Data & Intelligence Tokens for the full schema.

---

Pattern 2: Historical Comparison

Use case: Compare the new report to the previous quarter.

Setup:

1. Catch Hook + filter to signal
2. Google Sheets → Lookup Spreadsheet Row (find previous token for this brand)
3. Webhooks by Zapier → GET previous report’s REST endpoint
4. Code by Zapier → calculate delta (current - previous)
5. Append comparison to sheet or email

---

Pattern 3: Multi-Destination Fan-Out

Use case: Same data to Google Sheets + Notion + Airtable.

Setup: One Catch Hook → filter → add parallel “create row/page/record” actions for each destination. A single webhook payload feeds all of them.

---

Pattern 4: Webhook Signature Verification (Optional)

Surmado signs every webhook with X-Surmado-Signature (HMAC-SHA256 over the canonicalized JSON body). For high-stakes workflows, verify the signature in a Code by Zapier step before acting. See the API Integration Guide for the verification algorithm.

---

Troubleshooting

Issue 1: Catch Hook Doesn’t Fire

Symptom: Zap stays silent when a Surmado report completes.

Causes:

• webhook_url wasn’t included on the report creation call
• Zapier URL doesn’t use HTTPS (Surmado requires HTTPS — Zapier always uses it, but check for typos)
• The Zap is turned off
• The report itself failed (check for a report.failed event instead)

Fix:

• Use webhook.site as a staging URL to confirm Surmado is sending the payload
• Check the report’s status via GET /v1/reports/{report_id} — if failed, you’ll see a report.failed webhook, not completed
• Turn on the Zap and run a test report

---

Issue 2: Fields Show Empty in Google Sheets / Notion

Symptom: Destination rows have blank cells.

Causes:

• Field path uses single underscore instead of double (report_summary_presence_score vs report__summary__presence_score)
• Field doesn’t exist on that product (e.g. Scan reports don’t have presence_score; Strategy doesn’t have any summary fields)
• The source intelligence didn’t populate that field (e.g. top_competitor can be null if the brand has no identified competitors)

Fix:

• Use Zapier’s field picker instead of typing paths manually
• Verify the product: report__product tells you which summary fields to expect
• For AI Visibility, summary fields come from the extractor — see Structured Data & Intelligence Tokens for the field list

---

Issue 3: REST API Fetch Returns 401 Unauthorized

Symptom: Webhooks by Zapier GET step fails with 401.

Cause: Missing or malformed Authorization header.

Fix: Confirm the header is Authorization: Bearer sur_live_... (including the Bearer prefix). Or use X-API-Key: sur_live_... as an alternative.

---

Issue 4: Duplicate Rows in Google Sheets

Symptom: Same report appears twice.

Causes:

• Surmado retries failed webhook deliveries (3 attempts with backoff) — if your Zap is slow, Surmado may retry before Zapier confirms receipt
• You configured the webhook_url on two reports for the same brand

Fix:

• Respond quickly — Zapier’s Catch Hook is fast by default, but an overloaded Filter or Code step can delay the response past Surmado’s 30-second timeout
• Deduplicate on report__id (Zapier’s Formatter or Google Sheets lookup can check for existing rows before inserting)

---

Issue 5: Presence Score Looks Like 0-1 Instead of 0-100

Symptom: Presence score reads 0.342 instead of 34.2.

Cause: You’re looking at a stale field path (the underlying visibility_metrics.presence_rate legacy format). The summary field report.summary.presence_score is already normalized to 0-100.

Fix: Use report__summary__presence_score directly — no multiplication needed.

---

Best Practices

1. Use Consistent Zap Names

• AI Visibility → Google Sheets (Client Dashboard)
• Site Audit → Notion Database
• Strategy → Email Leadership

Why: Easy to identify in Zapier’s dashboard at 50+ Zaps.

---

2. Add Error Notifications

Add a final step to critical Zaps that emails or Slacks you if an earlier step fails. Zapier’s built-in error notifications are silent by default.

---

3. Use Folders for Organization

Zapier folders (Professional plan):

• Client Reporting — all client dashboard Zaps
• Internal Monitoring — your own reports
• Alerts — competitive alerts, at-risk clients

---

4. One Catch Hook per Product

Run one Catch Hook Zap per product (Signal / Scan / Solutions), not one per brand. Filter on report__product inside the Zap. You only need to configure webhook_url once per brand/report creation.

---

5. Store Raw Payloads for Replay

Log the full webhook payload to a “raw events” sheet or database. If your downstream logic changes later, you can replay historical events without re-running reports.

---

Zapier Task Estimation

Single report workflows:

• Tracking (Catch Hook → Filter → Sheets): 3 tasks
• With Slack alert: 4 tasks
• Notion with Code step: 4 tasks
• Full agency workflow with conditional alert: 5-6 tasks

Agency dashboards (20 clients/month):

• Basic tracking: ~60-80 tasks/month
• With alerts and multi-destination: ~100-140 tasks/month

Recommended plan:

• 1-5 clients: Starter ($20/month, 750 tasks)
• 5-20 clients: Starter still works for most; Professional ($50/month) adds Paths + Folders
• 20+ clients: Professional with folders and filters

---

Frequently Asked Questions

Can I trigger Zaps without configuring a webhook?

Yes — as a fallback, Gmail can trigger on emails from hi@surmado.com (Surmado also notifies via email when reports complete). But webhooks are faster, more reliable, and carry the full summary payload. Prefer webhooks.

Do I need to pay for both Zapier and Surmado?

Yes. Zapier is a separate automation platform. Surmado provides reports, the REST API, and webhook delivery. Zapier connects the two.

Can I share Zaps with clients?

Yes (Professional plan). Use Zapier Transfer to copy a Zap to a client’s Zapier account. They can customize for their needs.

What if the summary fields change?

Intelligence Token formats (SIG-, SCN-, SOL-) are stable. Summary field names can grow over time (new fields added), but we aim not to remove or rename existing fields. We’ll notify API consumers of breaking changes.

Can I use Zapier for bulk historical analysis?

Partially. You can manually re-trigger reports for brands you want to refresh. For bulk analysis across many historical reports, use the REST API directly (GET /v1/reports is paginated) — see the API Integration Guide.

Does Zapier work with Site Audit content gaps?

Yes. Site Audit payloads include report.summary.content_gaps_summary as an executive-summary string, and report.summary.quick_wins.content_gaps as a prioritized recommendation. For the full gap list, fetch the REST API and read public_intelligence.data.audit_data.enrichment.content_gaps.

Does Zapier work with Strategy reports?

Partially. Strategy webhooks carry the token and the PDF link, not a structured summary. Use them to trigger completion-based workflows (send the PDF, create a task, notify leadership). Structured Strategy data isn’t exposed via the REST API today — roadmap-dependent.

---

Need help setting up Zapier integrations? Contact hi@surmado.com with your use case — we can provide custom Zap templates or integration support.