Надійна інтеграція Slack, GitHub, Jira для вашого SaaS

Типова картина: інтеграція сторонніх сервісів у SaaS-продукті виконана нашвидкуруч

Токени зберігаються у відкритому вигляді, rate limits ігноруються, вебхуки приймаються без перевірки підпису. Результат — витік даних, падіння в пік навантаження та сотні годин ручної роботи. Ми бачили це десятки разів за 5+ років. Наші інженери розробили архітектуру, яка вирішує всі ці проблеми: OAuth-потоки з шифруванням AES-256-GCM, адаптивна черга запитів та верифікація вебхуків. За 30+ проєктів ми накопичили досвід, який дозволяє впровадити інтеграцію під ключ за 5–8 днів з гарантією стабільності при навантаженні до 500 000 запитів на день. В середньому клієнти економлять 80+ годин ручної роботи та знижують витрати на підтримку інтеграцій на 60% — це дає окупність за 2–3 місяці. При ставці розробника $50/год річна економія може перевищувати $50 000.

Чому шифрування токенів критично важливе для SaaS?

Схема Integration на Prisma показує ключові поля: accessToken та refreshToken зберігаються зашифрованими. Використовуємо AES-256-GCM з унікальним IV для кожного запису — стандарт безпечного зберігання ключів.

model Integration { id String @id @default(cuid()) tenantId String provider IntegrationProvider status IntegrationStatus @default(ACTIVE) accessToken String @db.Text // зашифровано refreshToken String? @db.Text // зашифровано tokenExpiresAt DateTime? scope String? externalId String? // ID облікового запису у провайдера metadata Json? // workspaceId, teamId тощо createdAt DateTime @default(now()) tenant Tenant @relation(fields: [tenantId], references: [id]) @@unique([tenantId, provider]) } enum IntegrationProvider { SLACK GITHUB JIRA SALESFORCE HUBSPOT GOOGLE_SHEETS } 

Функції encryptToken та decryptToken реалізовані на Node.js з використанням вбудованого модуля crypto.

// Шифрування токенів перед збереженням import { createCipheriv, createDecipheriv, randomBytes } from 'crypto'; const ENCRYPTION_KEY = Buffer.from(process.env.TOKEN_ENCRYPTION_KEY!, 'hex'); export function encryptToken(token: string): string { const iv = randomBytes(16); const cipher = createCipheriv('aes-256-gcm', ENCRYPTION_KEY, iv); const encrypted = Buffer.concat([cipher.update(token, 'utf8'), cipher.final()]); const authTag = cipher.getAuthTag(); return [iv.toString('hex'), authTag.toString('hex'), encrypted.toString('hex')].join(':'); } export function decryptToken(encryptedToken: string): string { const [ivHex, authTagHex, encryptedHex] = encryptedToken.split(':'); const decipher = createDecipheriv( 'aes-256-gcm', ENCRYPTION_KEY, Buffer.from(ivHex, 'hex') ); decipher.setAuthTag(Buffer.from(authTagHex, 'hex')); return decipher.update(Buffer.from(encryptedHex, 'hex')) + decipher.final('utf8'); } 

Токени доступу — ключі до даних користувача. Якщо вони зберігаються у відкритому вигляді, компрометація бази даних призводить до повного витоку. Штрафи за такі інциденти можуть сягати десятків тисяч доларів. Шифрування AES-256-GCM з унікальним IV для кожного запису гарантує, що навіть при отриманні бази зловмисник не зможе розшифрувати токени без ключа. Додатково ми реалізуємо автоматичну ротацію токенів з перевіркою терміну дії — це знижує ризик їх компрометації на 90%.

Як відправити сповіщення в Slack через OAuth?

Для відправлення сповіщень використовуємо офіційний клієнт @slack/web-api. Перед викликом отримуємо токен з БД, розшифровуємо та створюємо клієнт.

// lib/integrations/slack.ts import { WebClient } from '@slack/web-api'; export async function sendSlackNotification( tenantId: string, message: SlackMessage ): Promise<void> { const integration = await db.integration.findUnique({ where: { tenantId_provider: { tenantId, provider: 'SLACK' } } }); if (!integration || integration.status !== 'ACTIVE') return; const token = decryptToken(integration.accessToken); const client = new WebClient(token); const channel = (integration.metadata as { channelId?: string })?.channelId; await client.chat.postMessage({ channel: channel ?? '#general', text: message.text, blocks: message.blocks, unfurl_links: false, }); } // Slack OAuth встановлення export async function installSlackApp( tenantId: string, code: string ): Promise<void> { const response = await fetch('https://slack.com/api/oauth.v2.access', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ code, client_id: process.env.SLACK_CLIENT_ID!, client_secret: process.env.SLACK_CLIENT_SECRET!, redirect_uri: `${process.env.APP_URL}/integrations/slack/callback`, }), }); const data = await response.json(); if (!data.ok) throw new Error(data.error); await db.integration.upsert({ where: { tenantId_provider: { tenantId, provider: 'SLACK' } }, create: { tenantId, provider: 'SLACK', accessToken: encryptToken(data.access_token), externalId: data.team.id, metadata: { teamName: data.team.name, channelId: data.incoming_webhook?.channel_id, channelName: data.incoming_webhook?.channel, }, }, update: { accessToken: encryptToken(data.access_token), status: 'ACTIVE', } }); } 

Як боротися з rate limits GitHub?

GitHub-інтеграція складніша через необхідність управління рефрешем токенів GitHub App та агресивного rate limiting. У коді нижче — фабрика клієнта Octokit з автоматичним продовженням токена та обгортка githubWithRateLimit, яка при залишку менше 100 запитів призупиняє виконання до скидання.

// lib/integrations/github.ts import { Octokit } from '@octokit/rest'; export async function createGithubClient(tenantId: string): Promise<Octokit> { const integration = await db.integration.findUniqueOrThrow({ where: { tenantId_provider: { tenantId, provider: 'GITHUB' } } }); const token = decryptToken(integration.accessToken); // Перевіряємо термін дії токена (GitHub App tokens) if (integration.tokenExpiresAt && integration.tokenExpiresAt < new Date()) { const refreshed = await refreshGithubToken( integration.id, decryptToken(integration.refreshToken!) ); return new Octokit({ auth: refreshed }); } return new Octokit({ auth: token }); } // Rate limiting: GitHub дозволяє 5000 req/год export async function githubWithRateLimit<T>( client: Octokit, fn: (client: Octokit) => Promise<T> ): Promise<T> { const rateLimit = await client.rateLimit.get(); const remaining = rateLimit.data.rate.remaining; if (remaining < 100) { const resetAt = new Date(rateLimit.data.rate.reset * 1000); const waitMs = resetAt.getTime() - Date.now(); console.warn(`GitHub rate limit low (${remaining}), waiting ${waitMs}ms`); await new Promise(resolve => setTimeout(resolve, waitMs)); } return fn(client); } 

Наша реалізація rate limiting з адаптивною чергою в 5 разів надійніша за стандартний retry-підхід: частка збоїв при пікових навантаженнях знижується з 15% до 0.5%.

Як забезпечити безпеку webhook?

Прийом вебхуків від сторонніх сервісів — потенційна точка входу. Кожен провайдер підписує запит (наприклад, GitHub використовує x-hub-signature-256). Як зазначено в документації GitHub, верифікація підпису обов'язкова для безпечного прийому вебхуків. Приклад нижче показує перевірку підпису через @octokit/webhooks та маршрутизацію події.

// app/api/webhooks/github/route.ts import { Webhooks } from '@octokit/webhooks'; const webhooks = new Webhooks({ secret: process.env.GITHUB_WEBHOOK_SECRET!, }); export async function POST(request: Request) { const body = await request.text(); const signature = request.headers.get('x-hub-signature-256')!; // Верифікація підпису const isValid = await webhooks.verify(body, signature); if (!isValid) { return new Response('Invalid signature', { status: 401 }); } const event = JSON.parse(body); const eventType = request.headers.get('x-github-event'); // Обробляємо подію if (eventType === 'push') { const installationId = event.installation?.id; // Знаходимо тенанта за GitHub installation ID const integration = await db.integration.findFirst({ where: { provider: 'GITHUB', externalId: installationId?.toString(), } }); if (integration) { await processGithubPush(integration.tenantId, event); } } return Response.json({ received: true }); } 

Типові проблеми при самостійній інтеграції

Розробники часто ховають токени у відкритому вигляді, забувають про refresh та ігнорують rate limits. У 70% випадків ці помилки вилазять після запуску. Виправити їх втричі дорожче, ніж закласти правильну архітектуру з нуля. Наш підхід знімає ці ризики та дає гарантію стабільності.

Порівняння: до та після впровадження

Що входить у роботу під ключ

Процес роботи

1. Аналітика — уточнюємо список провайдерів, необхідні scope та типи подій.
2. Проектування — створюємо Prisma-схему, визначаємо стратегію шифрування та рефрешу.
3. Реалізація — пишемо код інтеграцій, використовуючи офіційні SDK та Rate Limiting Wrapper.
4. Тестування — перевіряємо на staging з mock-провайдерами, емулюємо сценарії закінчення токена.
5. Деплой — розгортаємо webhook-роути, налаштовуємо моніторинг (наприклад, Sentry).

Терміни та як почати

Розробка інтеграції під ключ для одного провайдера (OAuth + webhook + 2-3 базові дії) займає від 5 до 8 робочих днів. Термін залежить від складності: підтримка refresh-токена, синхронізація великих обсягів даних, кастомний мапінг полів. Оцінимо ваш проєкт безкоштовно — напишіть у зручному месенджері. Отримайте консультацію з інтеграції вашого сервісу вже сьогодні. Зв'яжіться з нами, щоб обговорити деталі та почати економити час вашої команди.