Надійна інтеграція 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-токена, синхронізація великих обсягів даних, кастомний мапінг полів. Оцінимо ваш проєкт безкоштовно — напишіть у зручному месенджері. Отримайте консультацію з інтеграції вашого сервісу вже сьогодні. Зв'яжіться з нами, щоб обговорити деталі та почати економити час вашої команди.

Розробка API: REST, GraphQL, WebSocket, tRPC

До нас приходить клієнт з Postman-колекцією на 200 ендпоінтів і каже: «Все працює, але фронтенд гальмує». Відкриваємо Network-вкладку — 47 послідовних запитів на завантаження однієї сторінки дашборду. Кожен чекає попереднього. Це не проблема швидкості сервера — це проблема архітектури API. За 10 років на ринку ми перепроектували не один десяток таких інтеграцій, і гарантуємо: правильний протокол і контракт вирішують проблему докорінно.

Коли REST перестає справлятися

REST добре працює для простих CRUD-операцій. Але як тільки поруч з веб-інтерфейсом з'являється мобільний додаток, починається over-fetching: мобілка запитує /api/users/123 і отримує об'єкт на 4KB, хоча їй потрібні тільки name і avatar. Помножте на список з 50 користувачів — 200KB трафіку замість 8KB.

GraphQL вирішує це через selection sets. Клієнт описує саме ті поля, які йому потрібні, і сервер повертає саме їх. На проекті з React Native + Next.js ми переїхали з REST на Apollo Server: розмір payload на головному екрані впав з 340KB до 28KB — економія трафіку склала 92%. Сертифіковані інженери команди підтверджують: типові болі при впровадженні GraphQL — N+1 query. Резолвер для поля author у поста викликає SELECT * FROM users WHERE id = ? для кожного поста у списку. На сторінці з 20 постами — 21 запит до бази. Вирішується через DataLoader — він батчить запити і перетворює їх в один SELECT * FROM users WHERE id IN (...).

Що таке tRPC і чим він кращий за REST/GraphQL?

Якщо весь стек на TypeScript (Next.js + Node/Bun), tRPC прибирає цілий шар проблем. Ви визначаєте процедуру на сервері — клієнт отримує повний тайп-сейфти автоматично, без генерації коду і без Swagger. Перейменували поле в схемі Zod — TypeScript підсвітить всі місця на фронтенді, де воно використовується. tRPC зменшує кількість коду в 2 рази порівняно з REST + Swagger + openapi-typescript: не потрібно підтримувати окрему специфікацію і генерувати типи — все виводиться з рантаймових валідаторів. Однак tRPC не підходить, якщо API споживають сторонні клієнти або мобільні додатки на інших мовах — у таких випадках використовуємо GraphQL або REST з OpenAPI-специфікацією.

WebSocket і реальний час: коли SSE, коли WS?

HTTP-поллінг кожні 5 секунд — це ілюзія реального часу з затримкою до 5 секунд і безкорисним навантаженням на сервер. Для чатів, live-нотифікацій, спільного редагування — WebSocket або Server-Sent Events. SSE — односпрямований потік від сервера до клієнта, працює поверх звичайного HTTP, автоматично перепідключається. Підходить для нотифікацій, стрімінгу даних, прогрес-барів. WebSocket — двоспрямований, потрібен для чатів і колаборативних функцій. Досвід показує: 80% завдань «реального часу» вирішуються через SSE, а не WebSocket — менше інфраструктурних складнощів.

Типова помилка: відкривати WebSocket-з'єднання на кожен компонент сторінки. На одному проекті дашборд відкривав 12 паралельних WS-з'єднань. Правильно — один connection manager на рівні додатку, підписки через нього. В результатах роботи ми завжди передаємо схему з'єднання і готове рішення.

Swagger / OpenAPI як контракт

Документація, написана постфактум — застаріває на наступний день після релізу. Ми пишемо специфікацію OpenAPI 3.1 до початку розробки, вона стає контрактом між фронтендом і бекендом. Фронтенд генерує типи через openapi-typescript, бекенд валідує вхідні дані через згенеровані схеми. Розбіжність контракту з реалізацією ловиться на CI, а не на рев'ю. Для Laravel — l5-swagger або dedoc/scramble. Для Node.js — @fastify/swagger або Zod + zod-to-openapi.

Як правильно аутентифікувати API?

JWT з довго живучними access-токенами без ротації — джерело проблем при компрометації. Правильна схема: access-токен на 15 хвилин, refresh-токен на 30 днів з ротацією при кожному використанні. Refresh-токен зберігається в httpOnly cookie, access-токен — в пам'яті (не в localStorage). Для міжсервісної взаємодії — API Keys з scope-обмеженнями або mTLS. OAuth 2.0 з PKCE для публічних клієнтів (SPA, мобілки).

Версіонування і зворотна сумісність

Ламаючі зміни в API без версіонування ламають клієнтів. Три підходи ми використовуємо в проектах:

Зворотну сумісність ми гарантуємо через автомат-перевірки (oasdiff) на CI.

Як ми розробляємо API: покроковий план

1. Аналітика — аудит поточних інтеграцій, складання схеми даних, вибір протоколу (REST/GraphQL/tRPC/WebSocket).
2. Проектування контракту — OpenAPI або SDL (GraphQL) до першого рядка коду.
3. Розробка — реалізація за контрактом, модульні тести на кожен ендпоінт.
4. Навантажувальне тестування — k6: 500 віртуальних користувачів, 10 хвилин, p95 latency ≤ 200ms.
5. Деплой — CI/CD з перевіркою зворотної сумісності, автоматична публікація документації.
6. Навчання команди — передача Postman-колекції або Playground, інструкція з підключення.

Що входить в роботу (deliverables)

• OpenAPI 3.1 специфікація (або SDL для GraphQL).
• Згенеровані клієнтські типи для TypeScript / Dart / Kotlin.
• Набір автотестів з покриттям всіх ендпоінтів (модульні + інтеграційні).
• Навантажувальні тести (k6) і звіт (p50/p95/p99 latency, RPS).
• Документація в Swagger UI / Redoc / GraphiQL.
• Навчання команди (2–4 години воркшопу).
• Підтримка протягом 30 днів після здачі (за договором).

Наш досвід

• 10+ років на ринку розробки API.
• 200+ завершених проектів (REST, GraphQL, WebSocket, tRPC).
• 50+ сертифікованих інженерів (AWS, Kubernetes, API Design).
• Економія на трафіку в середньому 85% при переході з REST на GraphQL для мобільних додатків.
• 100% зворотна сумісність — жодного зламаного клієнта за останні 3 роки.

Терміни

Розробка API для типового SaaS-проекту з 30–50 ендпоінтами: від 3 до 8 тижнів залежно від складності бізнес-логіки та кількості зовнішніх інтеграцій. Міграція існуючого REST API на GraphQL — від 2 до 6 тижнів. Додавання WebSocket-шару до готового бекенду — від 1 до 3 тижнів. Вартість розраховується індивідуально після аудиту. Отримайте консультацію — зв'яжіться з нами, щоб обговорити ваш проект.