Parallel ⇄ Attio Active Monitoring

An Attio app that integrates with Parallel's Web Systems monitoring API to automatically track and log company news updates.

Overview

This app allows you to:

• Create Parallel monitors for Company records in Attio
• Automatically receive webhook notifications when news events are detected
• Store structured Markdown updates in Company attributes
• Track monitor status and last check times

Features

Company Record Action: "Monitor Company News"

• One-click setup: Create a Parallel monitor directly from any Company record
• Idempotent: Prevents duplicate monitors for the same company
• Customizable: Configure query and cadence (hourly/daily/weekly)
• Status tracking: Monitor status displayed in Company attributes

Automatic News Ingestion

• Real-time updates: Webhooks deliver news events as they're detected
• Structured logging: Markdown-formatted updates with dates, sources, and detection timestamps
• Deduplication: Automatically prevents duplicate event entries
• Error handling: Robust handling of failures with status updates

Company Attributes

The app creates and manages these attributes on Company records:

Attribute	Type	Description
parallel_monitor_id	Text	The ID of the active Parallel monitor
monitor_status	Select	Current status: none, active, paused, failed
last_news_check	Date	Last time the monitor checked for news
news_updates	Text (multiline)	Markdown log of news updates (reverse-chronological)

Installation

1. Install Dependencies

npm install

2. Configure Parallel API Key Connection

1. In Attio, go to Settings → Apps → Parallel
2. Click Add Connection
3. Select Secret as the connection type
4. Enter your Parallel API key from Parallel Dashboard
5. Save the connection

Note: Each user needs to configure their own connection before using the app. The error "no user connection" means you haven't set up this connection yet.

3. Deploy the App

npm run build
npm run attio deploy

Usage

Creating a Monitor

1. Open any Company record in Attio
2. Click the "Monitor Company News" action
3. Customize the query (or use the default)
4. Select monitoring cadence (hourly, daily, or weekly)
5. Click "Create Monitor"

The default query template:

Extract recent news and material updates about [Company Name]. 
Focus on product launches, funding, partnerships, and leadership changes.

Viewing News Updates

News updates appear in the news_updates attribute on the Company record in reverse-chronological order:

### Event Date: 2025-01-15
Detected: 2025-01-15T20:30:00Z
EventGroupID: mevtgrp_abcdef

[Parallel event output content here]

Sources:
- https://example.com/article1
- https://example.com/article2

---

Monitor Status

Check the monitor_status attribute:

• active: Monitor is running normally
• paused: Monitor is temporarily disabled
• failed: Monitor encountered an error
• none: No monitor configured

Development

Local Development

1. Start the dev server:

npm run dev

2. Use a tunnel (e.g., ngrok) to expose webhooks:

ngrok http 3000

3. Update your Parallel webhook URL to point to your tunnel

Webhook Testing

The webhook endpoint is: /webhooks/parallel-monitor-events

Example webhook payload:

{
  "type": "monitor.event.detected",
  "timestamp": "2025-10-27T14:56:05.619331Z",
  "data": {
    "monitor_id": "monitor_xxx",
    "event": {
      "event_group_id": "mevtgrp_xxx"
    },
    "metadata": {
      "company_record_id": "company_uuid",
      "company_name": "Acme Corp",
      "created_by": "user@example.com"
    }
  }
}

Code Quality

Run type checking:

npm run build

Run formatting:

npm run format

Run linting:

npm run lint

Fix linting issues:

npm run lint:fix

Architecture

File Structure

src/
├── app.ts                          # Main app entry point
├── app.settings.ts                 # App settings schema
├── parallel/                       # Parallel API integration
│   ├── parallel-client.ts          # Generic API client
│   ├── parallel-error.ts           # Error handling
│   └── monitors/
│       ├── schema.ts               # Zod schemas
│       ├── create-monitor.server.ts
│       ├── get-event-group.server.ts
│       └── create-monitor-and-update-company.server.ts
├── attio/                          # Attio API integration
│   ├── schemas.ts                  # Zod schemas
│   ├── ensure-company-attributes.ts
│   ├── get-company.ts
│   ├── find-company-by-monitor.ts
│   └── update-company.ts
├── webhooks/                       # Webhook handlers
│   └── parallel-monitor-events.webhook.ts
├── components/                     # React components
│   └── create-monitor-dialog.tsx
├── record/actions/                 # Record actions
│   └── company-create-monitor-action.tsx
└── utils/                          # Utilities
    ├── logger.ts
    └── format-monitor-event.ts

Data Flow

Monitor Creation:

1. User clicks action on Company record
2. Dialog opens with pre-filled query
3. Server creates monitor via Parallel API
4. Company record updated with monitor ID and status

Event Ingestion:

1. Parallel detects news event
2. Webhook sent to Attio app
3. App fetches full event group details
4. Event formatted as Markdown
5. Prepended to Company's news_updates
6. last_news_check updated

Troubleshooting

Common Issues

Issue	Solution
"No user connection"	You haven't configured your Parallel API key connection yet. Go to Attio → Settings → Apps → Parallel → Add Connection → Select "Secret" → Enter your Parallel API key
"Connection Error: No connection configured"	Same as above - add your connection in Attio app settings
"API key is invalid or expired"	Your Parallel API key is incorrect. Get a fresh key from Parallel Dashboard and update your connection
"Monitor already active"	This company already has a monitor. Check the parallel_monitor_id attribute
Events not appearing	Check webhook logs; verify webhook URL is correct in Parallel dashboard
Monitor status shows "failed"	Check Parallel dashboard for error details

How to Set Up Connection (Step-by-Step)

IMPORTANT: The connection must be configured through the Attio app's connection flow, not as a general workspace connection.

Option 1: Through App Settings (Recommended)

1. In Attio, click Settings (gear icon in top right)
2. Go to Apps in the left sidebar
3. Find Parallel in your installed apps
4. Click on it to open app settings
5. Look for a Connections section or Configure button
6. Click Add Connection or the + button
7. You should see a prompt to connect to Parallel
8. Enter your Parallel API key from https://parallel.ai
9. Save the connection
10. Refresh your Attio page

Option 2: During First Use

Sometimes Attio will prompt you to configure the connection when you first try to use an action:

1. Try clicking the "Monitor Company News" action
2. If you see a prompt to "Configure Connection" or "Connect to Parallel", click it
3. Enter your Parallel API key
4. Save and retry

Still Not Working?

The app might need to be deployed/published properly. If you're testing locally with npm run dev:

1. Make sure the dev server is running
2. The connection configuration happens in the Attio platform, not in code
3. Try running: npm run build then reload Attio

If you're deploying the app:

1. Run: npm run build
2. Deploy using: attio deploy (or your deployment method)
3. After deployment, configure the connection in Attio UI
4. Each user needs to configure their own connection

Note: The connection test now runs automatically when you click the action. You'll get a clear error message if the connection is missing or invalid.

Logs

The app uses structured JSON logging. Key log fields:

• timestamp: ISO timestamp
• level: info, warn, error
• event_type: Type of webhook received
• monitor_id: Parallel monitor ID
• company_record_id: Attio company record ID
• event_group_id: Parallel event group ID
• error_msg: Error message if applicable

Debug Mode

Enable verbose logging in your Attio app settings.

API Reference

Parallel API

• Base URL: https://api.parallel.ai
• Auth: x-api-key header (no Bearer prefix)
• Docs: Parallel API Documentation

Attio API

• Docs: Attio SDK Documentation

Security

• API keys stored securely via Attio Secret connections
• Webhook payloads validated with Zod
• All errors return 200 to prevent retry storms
• No sensitive data logged

License

Private repository. All rights reserved.

Support

For issues or questions:

1. Check the troubleshooting section above
2. Review logs for error details
3. Contact your Parallel support team