Integrations¶

OWNER: aimee ALSO_USED_BY: anna (implementation), faye, sytske

B2B customers expect their SaaS tools to connect to their existing stack. Integrations are not optional — they are a competitive requirement and a retention driver. Lack of integrations is cited as a top-3 churn reason.

Integration Architecture Overview¶

Layer	Description	Budget
Outbound webhooks	Your app pushes events to customer endpoints	30-50 hours
REST API	Third parties read/write your data	60-100 hours (if API-first, already built)
OAuth2 marketplace	Third-party apps authenticate against your platform	60-80 hours
Native integrations	Pre-built connectors (Slack, Teams, Jira, etc.)	20-40 hours each
Zapier/Make	No-code automation platform connectors	30-50 hours each

CHECK: Identify the top 3 integrations from client's customer research during scoping CHECK: API-first architecture means the REST API is already built — integrations build on top

Webhook System (Outbound)¶

SCOPE_ITEM: outbound_webhooks INCLUDES: Customer registers webhook endpoint URL per event type INCLUDES: Configuration UI: URL, events to subscribe, secret key INCLUDES: Events delivered as HTTP POST with JSON payload INCLUDES: Payload includes: event_type, timestamp, data, webhook_id INCLUDES: Request signed with HMAC-SHA256 (shared secret per endpoint) INCLUDES: Delivery log visible to customer (timestamp, status code, response time) INCLUDES: Automatic retry on failure (exponential backoff: 1min, 5min, 30min) INCLUDES: Maximum 3 retry attempts before marking as failed INCLUDES: "Test webhook" button (sends sample event to configured URL) INCLUDES: Webhook event catalog documented in API docs

Webhook Events (Standard Set)¶

SCOPE_ITEM: webhook_event_catalog
INCLUDES: entity.created — new record created
INCLUDES: entity.updated — record modified (includes changed fields)
INCLUDES: entity.deleted — record removed
INCLUDES: user.invited — new user invited to org
INCLUDES: user.joined — user accepted invite
INCLUDES: user.removed — user removed from org
INCLUDES: subscription.created — new subscription started
INCLUDES: subscription.updated — plan changed
INCLUDES: subscription.cancelled — subscription cancelled
INCLUDES: invoice.paid — payment succeeded
INCLUDES: invoice.failed — payment failed

CHECK: Event names follow {resource}.{action} convention (like Stripe) CHECK: Payload must include enough data to be useful without requiring API callback CHECK: Never include secrets, passwords, or full PII in webhook payloads

Webhook Implementation Pattern¶

SCOPE_ITEM: webhook_implementation
INCLUDES: Webhook events enqueued to background job queue (never sent synchronously)
INCLUDES: Job processor sends HTTP POST with timeout (10 seconds)
INCLUDES: Response logging (status code, first 1KB of body, response time)
INCLUDES: Failed delivery enters retry queue with exponential backoff
INCLUDES: Dead letter queue after max retries (admin can inspect and replay)
INCLUDES: Per-endpoint rate limiting (100 events/minute default)
INCLUDES: Webhook endpoint health monitoring (auto-disable after 100 consecutive failures)

COMPLIANCE: Webhook payloads are tenant-scoped — never leak cross-tenant data CHECK: Webhook delivery should not block application operations — always async CHECK: Include X-Webhook-ID header for idempotent processing by consumers

REST API Design¶

SCOPE_ITEM: rest_api_design

API-First Principles¶

INCLUDES: All UI operations available via API (same endpoints) INCLUDES: OpenAPI 3.1 specification auto-generated from route definitions INCLUDES: API versioning via URL path (/api/v1/, /api/v2/) INCLUDES: Consistent resource naming (plural nouns: /projects, /users, /invoices) INCLUDES: Standard HTTP methods (GET, POST, PATCH, DELETE — no PUT unless full replace) INCLUDES: Cursor-based pagination (next_cursor, previous_cursor — not page/offset) INCLUDES: Filtering via query parameters (?status=active&created_after=2026-01-01) INCLUDES: Field selection (?fields=id,name,status for reduced payload) INCLUDES: Sorting (?sort=created_at:desc) INCLUDES: Consistent error format: { error: { code, message, details } }

Rate Limiting¶

INCLUDES: Rate limits per API key (configurable per plan) INCLUDES: Default: 100 req/min (starter), 500 req/min (pro), 2000 req/min (enterprise) INCLUDES: Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset INCLUDES: 429 Too Many Requests response with Retry-After header CHECK: Rate limits applied per-tenant, not per-user — org shares its quota

API Documentation¶

INCLUDES: Auto-generated API reference from OpenAPI spec (Scalar or Redoc) INCLUDES: Getting started guide with authentication examples INCLUDES: Code examples in cURL, JavaScript, Python INCLUDES: Changelog for API versions OPTIONAL: Interactive API explorer ("try it" in docs) CHECK: API docs are a product feature — invest in quality

GraphQL (Optional)¶

SCOPE_ITEM: graphql_api INCLUDES: GraphQL endpoint alongside REST (not replacing) INCLUDES: Schema stitched from domain modules INCLUDES: Query complexity limiting (prevent expensive nested queries) INCLUDES: Persisted queries for production (prevent arbitrary queries) OPTIONAL: Real-time subscriptions via GraphQL Subscriptions (WebSocket) CHECK: GraphQL adds 40-60 hours — only if client's customers are developers CHECK: REST is always the primary API — GraphQL is additive

OAuth2 App Marketplace¶

SCOPE_ITEM: oauth2_marketplace

OAuth2 Authorization Code Flow¶

INCLUDES: App registration portal (developer creates app: name, redirect URIs, scopes) INCLUDES: Client ID and client secret issued per app INCLUDES: Authorization endpoint: user sees consent screen, approves scopes INCLUDES: Token endpoint: app exchanges auth code for access + refresh tokens INCLUDES: PKCE required for public clients (SPAs, mobile apps) INCLUDES: Scope-based permissions (app requests specific scopes, user approves) INCLUDES: Token refresh (access token 1-hour, refresh token 30-day) INCLUDES: Token revocation endpoint COMPLIANCE: OAuth2 apps must declare all scopes upfront — no scope escalation post-consent

App Marketplace (If Applicable)¶

INCLUDES: Public listing of approved apps INCLUDES: App detail page (description, screenshots, permissions, reviews) INCLUDES: One-click install (triggers OAuth2 flow) INCLUDES: Installed apps management (view, disconnect, manage permissions) INCLUDES: App review process (GE client reviews before public listing) OPTIONAL: Private apps (only visible to specific orgs) CHECK: Full marketplace is 200+ hours — only if platform play is core to product CHECK: Start with OAuth2 infrastructure + private apps, add public marketplace later

Native Integrations¶

SCOPE_ITEM: native_integrations

Slack Integration¶

INCLUDES: Slack OAuth2 app registration INCLUDES: Channel selection for notifications INCLUDES: Event types configurable (new task, mention, status change) INCLUDES: Rich message formatting (blocks, buttons, links) INCLUDES: Slash commands (optional — /app-name status) OPTIONAL: Interactive messages (button clicks trigger app actions) CHECK: 20-30 hours for basic Slack integration

Microsoft Teams Integration¶

INCLUDES: Teams app registration (Azure AD) INCLUDES: Incoming webhook or Bot Framework INCLUDES: Channel notifications with adaptive cards INCLUDES: Tab integration (embed app page in Teams tab) OPTIONAL: Teams bot for interactive commands CHECK: 30-40 hours for basic Teams integration CHECK: Teams requires Azure AD app registration — more setup than Slack

Jira Integration¶

INCLUDES: Jira OAuth2 or API token authentication INCLUDES: Two-way sync: create Jira issue from app, update app from Jira webhook INCLUDES: Field mapping (app fields ↔ Jira fields) INCLUDES: Status sync (app status ↔ Jira status) OPTIONAL: Jira project selection per workspace CHECK: 40-60 hours for two-way Jira sync

CRM Integration (HubSpot / Salesforce)¶

INCLUDES: OAuth2 connection to CRM INCLUDES: Contact/company sync (bidirectional) INCLUDES: Activity/event push to CRM timeline INCLUDES: Deal/opportunity sync (if applicable) OPTIONAL: Embedded app in CRM sidebar CHECK: 40-80 hours per CRM, depending on sync depth CHECK: Salesforce integration is more complex than HubSpot — budget accordingly

ERP Integration (NL Market)¶

INCLUDES: Exact Online API integration (dominant NL ERP) INCLUDES: Twinfield / Visma integration INCLUDES: Invoice sync (push invoices to ERP) INCLUDES: Contact sync (bidirectional) OPTIONAL: General ledger posting CHECK: Exact Online has rate limits and session management quirks — budget 60-80 hours CHECK: ERP integrations are sticky — they significantly reduce churn

Email Integration¶

INCLUDES: Shared inbox (receive email, display in app) INCLUDES: Email forwarding setup (customer forwards to app-generated address) INCLUDES: Email → entity creation (email becomes a ticket, lead, or task) INCLUDES: Reply from app (sends email on behalf of user) OPTIONAL: Email tracking (open, click) CHECK: Email integration via Brevo Inbound or Mailjet Parse (EU preferred). SendGrid Inbound Parse or Postmark Inbound as secondary (US-based — EU data sovereignty risk). CHECK: 40-60 hours for basic email integration

Zapier / Make / n8n¶

SCOPE_ITEM: zapier_integration

Zapier App¶

INCLUDES: Triggers (webhook-based events that start Zaps) INCLUDES: Actions (API calls that Zapier can invoke) INCLUDES: Searches (lookup operations for Zapier data mapping) INCLUDES: OAuth2 authentication flow INCLUDES: Test data and sample payloads INCLUDES: Zapier CLI for local development and testing

Typical triggers:

INCLUDES: New [entity] created
INCLUDES: [Entity] updated
INCLUDES: [Entity] status changed
INCLUDES: New user joined org

Typical actions:

INCLUDES: Create [entity]
INCLUDES: Update [entity]
INCLUDES: Add user to org
INCLUDES: Send notification

CHECK: Zapier app must pass Zapier's review process for public listing CHECK: Budget 30-50 hours for Zapier app development and submission

Make (Integromat) Module¶

INCLUDES: Similar to Zapier — triggers, actions, searches INCLUDES: Make uses a different module format (JSON schema + communication) INCLUDES: Supports more complex multi-step scenarios than Zapier CHECK: Budget 20-30 hours (if Zapier is already built, Make reuses same API)

n8n Community Node¶

INCLUDES: Open-source workflow automation INCLUDES: Community node published to npm INCLUDES: Uses same REST API as Zapier/Make CHECK: Budget 10-20 hours (simple wrapper around existing API) CHECK: n8n is popular with self-hosted and privacy-conscious customers

Integration Infrastructure¶

SCOPE_ITEM: integration_infrastructure

Connection Management¶

INCLUDES: Per-org integration connections stored in DB (encrypted credentials) INCLUDES: Connection health checking (periodic test call, mark as disconnected) INCLUDES: Reconnection flow (re-authorize when token expires) INCLUDES: Connection audit log (who connected, when, what permissions) CHECK: OAuth2 tokens stored encrypted at rest (AES-256, key in Vault)

Integration Event Bus¶

INCLUDES: Internal event bus (Redis Streams) fires events for all entity changes INCLUDES: Webhook dispatcher listens to event bus, sends to registered webhooks INCLUDES: Integration connectors listen to event bus, push to external systems INCLUDES: Event bus is the single source of integration triggers CHECK: Never call integration endpoints from business logic — always via event bus CHECK: Event bus provides natural decoupling and retry/replay capability

Error Handling¶

INCLUDES: Integration errors do not block core application operations INCLUDES: Failed integration calls logged and retried INCLUDES: Customer notified of persistent integration failures (in-app + email) INCLUDES: Admin dashboard shows integration health across all tenants CHECK: Circuit breaker pattern for external API calls (open after 5 consecutive failures) CHECK: Timeout: 10 seconds for webhook delivery, 30 seconds for API sync calls