integrations

# Third-Party Integrations

The simplest integration that works is the best integration. If Zapier can do it, don't build a custom one. This skill helps you decide which integrations to build, how to build them simply, and how to handle the inevitable breakage.

## Core Principles

- Build integrations your customers ask for, not ones you think are cool.
- The simplest integration that works is the best integration. Zapier before custom code.
- Every integration is a maintenance burden. Each one can break when the third party changes their API.
- Authentication is the hardest part. Get OAuth right or use pre-built libraries.
- Always handle the failure case. APIs go down. Webhooks get lost. Plan for it.

## Integration Decision Framework

### Build vs. Buy vs. Skip

```
Should I build this integration?

1. Are 3+ customers asking for it?
   No → Skip it. Revisit when demand exists.
   Yes ↓

2. Can Zapier/Make/n8n handle it?
   Yes → Tell users to use Zapier. Don't build it yourself.
   No ↓

3. Is there a well-documented API with a good SDK?
   Yes → Build it (or have AI build it).
   No → Evaluate if the effort is worth the churn it prevents.
```

### Integration Priority for SaaS

**Build these first (most SaaS apps need them):**

| Integration | Why | Difficulty |
|-------------|-----|-----------|
| Stripe | Payments are core to your business | Medium (good docs, SDKs) |
| Email provider (Resend, SendGrid) | Transactional emails are required | Easy |
| Auth provider (Supabase Auth, Clerk) | Login is required | Easy (use their SDK) |
| Analytics (PostHog, Mixpanel) | You need to track usage | Easy (drop-in script) |

**Build these when customers ask:**

| Integration | Why | Difficulty |
|-------------|-----|-----------|
| Slack | Notifications where teams already work | Easy |
| Zapier | Lets users build their own integrations | Medium |
| Google/Microsoft OAuth | "Sign in with Google" is expected | Medium |
| Webhooks (outgoing) | Let customers receive events in their systems | Medium |

**Skip these until $10k+ MRR:**

| Integration | Why to Wait |
|-------------|------------|
| Salesforce | Complex API, long sales cycles to close deals that need it |
| Custom enterprise SSO (SAML) | Only needed for enterprise deals |
| Data warehouse exports | Build when you have data-heavy customers |

---

## Common Integration Patterns

### Pattern 1: OAuth Sign-In (Google, GitHub, etc.)

**What it does:** Let users log in with existing accounts.

**Tell AI:**
```
Add Google OAuth sign-in to my app.
I'm using [Supabase Auth / Clerk / NextAuth].
Requirements:
- "Sign in with Google" button on login page
- Create user record on first sign-in
- Link to existing account if email matches
- Handle the error case gracefully
```

**Setup checklist:**
```
- [ ] Create OAuth app in provider's developer console
- [ ] Set redirect URI to your production AND localhost URLs
- [ ] Store client ID and secret in environment variables (never in code)
- [ ] Test the full flow: sign in → callback → user created
- [ ] Test edge case: user signs up with email, then tries Google with same email
```

### Pattern 2: Sending Emails (Transactional)

**What it does:** Welcome emails, password resets, notifications.

**Recommended providers:**
- **Resend** — Simple API, good free tier, built for developers
- **SendGrid** — Established, more features, higher free tier
- **Postmark** — Best deliverability, focused on transactional email

**Tell AI:**
```
Set up transactional email with [Resend/SendGrid] for my [framework] app.
I need to send:
- Welcome email on signup
- Password reset email
- [Other emails you need]
Use environment variables for API keys.
Include error handling if the email fails to send.
```

### Pattern 3: Webhooks (Receiving)

**What it does:** Third-party services notify your app when something happens (e.g., Stripe payment succeeded).

**Tell AI:**
```
Create a webhook endpoint for [Stripe/service] in my [framework] app.
Requirements:
- Verify the webhook signature (critical for security)
- Handle these events: [list events, e.g., checkout.session.completed]
- Respond with 200 quickly, process async if needed
- Log the raw payload for debugging
- Handle duplicate events (idempotency)
```

**Webhook checklist:**
```
- [ ] Endpoint URL is configured in the third party's dashboard
- [ ] Webhook signature is verified on every request
- [ ] Endpoint responds with 200 within 5 seconds
- [ ] Failed processing retries gracefully
- [ ] Events are idempotent (processing the same event twice is safe)
- [ ] Raw payloads are logged for debugging
```

### Pattern 4: Webhooks (Sending)

**What it does:** Your app notifies customer systems when something happens.

**Tell AI:**
```
Add outgoing webhooks to my app so customers can receive events.
Requirements:
- Customers can register a webhook URL in settings
- Send POST requests with JSON payload when [events] occur
- Include a signature header for verification
- Retry failed deliveries 3 times with exponential backoff
- Show delivery status in the customer's dashboard
```

### Pattern 5: Zapier Integration

**What it does:** Lets your customers connect your app to 5,000+ other apps without you building each integration.

**When to build:** When multiple customers ask for integrations you don't want to build individually.

**Tell AI:**
```
Help me plan a Zapier integration for [product].
My app can:
- Triggers (things that happen): [e.g., new project created, task completed]
- Actions (things Zapier can do in my app): [e.g., create a task, update a record]
What API endpoints do I need to expose for Zapier?
```

---

## API Key Management

### For Your API Keys (Connecting to Services)

```
Rules:
- [ ] NEVER put API keys in code. Use environment variables.
- [ ] Different keys for development and production.
- [ ] Rotate keys if you accidentally commit one (immediately).
- [ ] Document which keys are needed in a .env.example file.
- [ ] Use the narrowest permissions possible for each key.
```

### For Your Customers' API Keys (If You Offer an API)

```
- [ ] Generate unique keys per customer
- [ ] Allow customers to revoke and regenerate keys
- [ ] Rate limit by API key
- [ ] Log usage by API key
- [ ] Hash stored keys (don't store in plain text)
```

---

## Error Handling for Integrations

Every integration will fail at some point. Plan for it:

```
Integration Error Handling Checklist:
- [ ] What happens if the API is down? (Queue and retry? Show error to user?)
- [ ] What happens if auth credentials expire? (Re-auth flow? Alert the user?)
- [ ] What happens if the API returns unexpected data? (Log and fail gracefully?)
- [ ] What happens if rate limits are hit? (Backoff and retry? Queue?)
- [ ] Is there a timeout? (Don't wait forever for a response)
- [ ] Are errors logged with enough context to debug?
```

---

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Building custom integrations nobody asked for | Wait for 3+ customer requests before building |
| API keys in source code | Environment variables, always |
| No webhook signature verification | Verify every incoming webhook. Unverified = security hole |
| No error handling on API calls | Every external call needs try/catch and a fallback |
| Building what Zapier can handle | Recommend Zapier to customers. Build only what Zapier can't |
| No retry logic for failed webhooks | Retry 3x with exponential backoff |
| Testing only the happy path | Test: API down, bad credentials, rate limited, timeout |

---

## Success Looks Like

- Core integrations (payments, email, auth) working reliably in production
- Third-party API keys stored securely in environment variables
- Webhook endpoints verified, idempotent, and logged
- Customers can connect the tools they need (directly or via Zapier)
- You can debug integration failures quickly with proper logging

---

## Related Skills

- **build** — Hand integration specs to AI tools for implementation
- **database** — Schema design for storing integration data
- **secure** — Secure API key storage and OAuth implementation
- **debug** — Diagnose integration failures