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