Intégrer des SaaS avec Claude Code : API keys, OAuth, webhooks et audit

Quand on crée des intégrations SaaS avec Claude Code, la première question n’est pas “quel endpoint appeler ?”. La première question est : comment autoriser proprement, comment réessayer sans créer de doublons, et comment prouver plus tard qui a fait quoi. Sans cette couche, même une simple notification Slack peut devenir un problème de sécurité, de facturation ou d’exploitation.

Ce guide transforme les API keys, OAuth, webhooks, limites de débit, retries, idempotence, logs d’audit, secrets et environnements de test en un workflow pratique pour Claude Code. Un webhook est un événement envoyé par un SaaS vers votre serveur. L’idempotence signifie qu’une opération répétée ne crée pas de résultat en double. Un log d’audit est l’enregistrement qui permet d’expliquer l’automatisation après coup.

Les exemples supposent Node.js 20 ou plus et peuvent être copiés dans un petit dossier scripts/.

Architecture d’intégration

Claude Code ne doit pas être le seul endroit où vit l’état de l’intégration. Claude Code planifie, génère et lance des commandes ; les tokens, l’état des retries et l’historique d’audit doivent rester dans le code du connecteur.

flowchart LR
  A[Claude Code] --> B[CLI or MCP connector]
  B --> C[Auth and secret store]
  B --> D[Retry and rate-limit wrapper]
  D --> E[SaaS API]
  E --> F[Webhook receiver]
  F --> G[Queue]
  G --> H[Worker]
  H --> I[Audit log]

La version minimale utile est un wrapper CLI, par exemple node scripts/slack-notify.mjs appelé depuis Claude Code. Si le workflow devient fréquent, transformez-le en serveur MCP afin de réutiliser le schéma d’entrée, les permissions et la gestion des erreurs. Les récepteurs webhook demandent plus d’effort, mais ils sont nécessaires quand Stripe, GitHub, Slack ou un autre SaaS déclenche le flux.

Quatre cas d’usage concrets

Le premier cas est l’exploitation des releases. Claude Code lit les commits GitHub non publiés, rédige les notes de version et publie un résumé court dans Slack. Les Slack Incoming Webhooks sont rapides à mettre en place, mais ils ne conviennent pas aux suppressions de messages ni aux flux de chat complexes ; il faut alors passer à la Slack Web API.

Le deuxième cas est l’automatisation de la facturation. Un webhook Stripe reçoit checkout.session.completed, enregistre le client dans un outil interne et place les échecs dans une file de retry. Vérification de signature, clés d’idempotence et séparation stricte entre test mode et live mode sont indispensables.

Le troisième cas est le triage support. Google Workspace OAuth permet à un backend de lire un CSV de support, Claude Code classe les lignes, puis des issues GitHub sont créées pour le suivi engineering. Comme le flux touche aux données utilisateur, OAuth avec des scopes étroits en lecture seule est plus sûr qu’une API key partagée.

Le quatrième cas est un tableau d’audit. Chaque action SaaS déclenchée par Claude Code est écrite en NDJSON pour voir l’acteur, le fournisseur, l’action, la cible et la clé d’idempotence. C’est utile même avant d’avoir une plateforme d’audit complète.

Choisir API key, OAuth, webhook ou connecteur

Méthode	Explication simple	Idéal pour	Point de vigilance
API key	Identifiant partagé côté serveur	Appels serveur Stripe, notifications Slack internes	Stockage en variables d’environnement ou secret manager, jamais en source
OAuth	Un utilisateur ou workspace accorde l’accès	Google Drive, GitHub Apps, actions par utilisateur	Refresh tokens et scopes doivent être conçus clairement
Webhook	Le SaaS envoie un événement à votre endpoint	Paiements Stripe, issues GitHub, événements Slack	Vérifier les signatures, accepter les doublons, ne pas supposer l’ordre
Connecteur CLI/MCP	Outil stable appelé par Claude Code	Runbooks, ops internes, workflows multi-SaaS	Mettre validation et logs dans le connecteur

La documentation Google OAuth 2.0 décrit le flux access token et refresh token. Avec GitHub et Slack aussi, gardez des logs avec l’acteur réel : “le bot l’a fait” ne suffit pas lorsqu’on enquête sur des permissions.

Checklist des variables d’environnement

Commencez par .env.example et partagez seulement les noms. Les vraies valeurs ne vont pas dans Git.

# .env.example
INTEGRATION_ENV=sandbox
SAAS_API_TOKEN=
SLACK_WEBHOOK_URL=
GITHUB_WEBHOOK_SECRET=
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
STRIPE_SECRET_KEY=sk_test_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx
AUDIT_LOG_PATH=logs/saas-audit.ndjson

# .gitignore
.env
.env.*
!.env.example
logs/

Avant de laisser Claude Code exécuter l’intégration :

• Séparez les clés live et test dans des environnements distincts.
• Ne collez jamais de secrets dans un prompt Claude Code.
• N’affichez jamais les headers Authorization ni les secrets webhook dans les erreurs.
• Démarrez OAuth en lecture seule, puis élargissez seulement si nécessaire.
• Déclarez les valeurs CI comme secrets, pas comme variables publiques du dépôt.
• Notez qui a fait la rotation d’une clé et à quelle date.

Wrapper pour retries et rate limits

Une limite de débit est le rythme maximal de requêtes autorisé par un fournisseur. Les APIs REST GitHub ont des limites primaires et secondaires ; en cas d’échec, il faut respecter les headers. Slack renvoie 429 Too Many Requests avec Retry-After. Ce comportement doit vivre dans le code, pas dans des consignes improvisées.

// scripts/saas-request.mjs
import crypto from "node:crypto";
import { pathToFileURL } from "node:url";

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

export async function saasRequest(url, options = {}) {
  const {
    method = "GET",
    token = process.env.SAAS_API_TOKEN,
    body,
    idempotencyKey = method === "POST" ? crypto.randomUUID() : undefined,
    maxRetries = 4,
    headers = {},
  } = options;

  for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
    const res = await fetch(url, {
      method,
      headers: {
        Accept: "application/json",
        ...(body ? { "Content-Type": "application/json" } : {}),
        ...(token ? { Authorization: `Bearer ${token}` } : {}),
        ...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
        ...headers,
      },
      body: body ? JSON.stringify(body) : undefined,
    });

    if (res.ok) return res;

    const retryAfter = Number(res.headers.get("retry-after"));
    const shouldRetry = [408, 409, 425, 429, 500, 502, 503, 504].includes(res.status);

    if (!shouldRetry || attempt === maxRetries) {
      const text = await res.text();
      throw new Error(`SaaS request failed: ${res.status} ${text.slice(0, 200)}`);
    }

    const backoffMs = Number.isFinite(retryAfter)
      ? retryAfter * 1000
      : Math.min(30000, 500 * 2 ** attempt);

    await sleep(backoffMs);
  }

  throw new Error("unreachable");
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  const url = process.argv[2];
  if (!url) throw new Error("Usage: node scripts/saas-request.mjs <url>");
  const res = await saasRequest(url);
  console.log(await res.text());
}

Avec les APIs comme Stripe qui supportent les clés d’idempotence, le même POST peut être réessayé sans risque. Pour vos workers, utilisez une clé du type provider + event_id + action et ignorez le traitement si elle existe déjà.

Vérification des webhooks

Les webhooks sont des entrées HTTP publiques. Sans vérification de signature, n’importe qui peut envoyer de faux événements. GitHub utilise X-Hub-Signature-256 ; Stripe utilise Stripe-Signature. La règle importante est de vérifier le raw body avant de parser le JSON.

1. Lire le raw body.
2. Lire le header de signature.
3. Calculer le HMAC avec le secret partagé.
4. Comparer avec une méthode timing-safe.
5. Enregistrer le delivery id comme clé d'idempotence.
6. Répondre 202 rapidement et traiter le travail lourd dans une queue.

// scripts/verify-github-webhook.mjs
import crypto from "node:crypto";
import http from "node:http";

const secret = process.env.GITHUB_WEBHOOK_SECRET;
if (!secret) throw new Error("Set GITHUB_WEBHOOK_SECRET");

function verifyGitHubSignature(rawBody, signatureHeader) {
  const received = Array.isArray(signatureHeader)
    ? signatureHeader[0]
    : signatureHeader ?? "";
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const receivedBytes = Buffer.from(received);
  const expectedBytes = Buffer.from(expected);

  return (
    receivedBytes.length === expectedBytes.length &&
    crypto.timingSafeEqual(receivedBytes, expectedBytes)
  );
}

http
  .createServer(async (req, res) => {
    const chunks = [];
    for await (const chunk of req) chunks.push(chunk);
    const rawBody = Buffer.concat(chunks);

    if (!verifyGitHubSignature(rawBody, req.headers["x-hub-signature-256"])) {
      res.writeHead(401);
      res.end("invalid signature");
      return;
    }

    const event = req.headers["x-github-event"];
    const delivery = req.headers["x-github-delivery"];
    console.log(JSON.stringify({ event, delivery, receivedAt: new Date().toISOString() }));

    res.writeHead(202, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ ok: true }));
  })
  .listen(3000, () => console.log("Listening on http://localhost:3000"));

Pour Stripe, utilisez en production constructEvent() du SDK officiel. Les secrets webhook de test et de production sont différents ; STRIPE_WEBHOOK_SECRET doit donc être propre à chaque environnement.

Logs d’audit

Un log d’audit est l’enregistrement qui permet d’expliquer une action automatisée. L’historique de discussion Claude Code ne suffit pas : il faut timestamp, acteur, fournisseur, action, cible, clé d’idempotence et statut.

{
  "ts": "2026-06-03T09:15:00.000Z",
  "actor": "claude-code",
  "provider": "github",
  "action": "create_issue",
  "target": "owner/repo#123",
  "idempotencyKey": "github:issue:customer-42:2026-06-03",
  "status": "succeeded"
}

// scripts/audit-log.mjs
import { appendFile, mkdir } from "node:fs/promises";
import { dirname } from "node:path";

export async function writeAudit(event) {
  const record = {
    ts: new Date().toISOString(),
    actor: event.actor ?? "claude-code",
    provider: event.provider,
    action: event.action,
    target: event.target,
    idempotencyKey: event.idempotencyKey,
    status: event.status ?? "started",
  };
  const file = process.env.AUDIT_LOG_PATH ?? "logs/saas-audit.ndjson";
  await mkdir(dirname(file), { recursive: true });
  await appendFile(file, `${JSON.stringify(record)}\n`, "utf8");
}

if (process.argv[1]?.endsWith("audit-log.mjs")) {
  await writeAudit({
    provider: "slack",
    action: "post_message",
    target: "#release",
    idempotencyKey: "demo-2026-06-03",
    status: "succeeded",
  });
}

NDJSON suffit pour une première version. Vous pourrez ensuite l’importer dans BigQuery, DuckDB ou une feuille de calcul.

Pièges fréquents

Le premier piège consiste à vouloir livrer des webhooks directement vers localhost. La documentation de dépannage GitHub rappelle qu’une URL webhook doit être publiquement accessible. Utilisez un service de forwarding en local et HTTPS en production.

Le deuxième piège est de faire confiance à l’ordre des webhooks. Les fournisseurs peuvent livrer des événements en retard ou dans un ordre différent. Utilisez les timestamps, delivery ids et l’état courant de la ressource.

Le troisième problème est le doublon créé par un retry. Paiements, issues, messages Slack et e-mails sont visibles par les utilisateurs. Ajoutez des clés d’idempotence aux POST et stockez les delivery ids déjà traités.

Le quatrième piège est un scope OAuth trop large. Commencez en lecture seule, sur un dossier ou workspace précis, avec des tokens courts. Élargissez seulement quand le risque est compris.

Le cinquième piège est de coller des secrets dans Claude Code. Demandez à Claude Code d’utiliser les noms de variables d’environnement ; les vraies valeurs restent dans un secret manager, un secret CI ou un .env local.

Quand créer une abstraction de connecteur

Le premier script peut être direct et simple. Quand l’autorisation, la pagination, les rate limits, les logs d’audit et le formatage d’erreurs reviennent dans trois workflows, créez un connecteur.

Nommez l’abstraction avec le langage métier : sendMessage(), createTicket(), recordPaymentEvent(), writeAudit(). Un simple callSlackApi() aide moins Claude Code qu’une fonction qui exprime le résultat attendu.

Pour les détails voisins, combinez cela avec Claude Code API Design Assistant et Claude Code API Testing. Pour la revue des risques, lisez Claude Code Security Best Practices avant l’accès production.

Références officielles

• Stripe : vérification de signature des webhooks
• Stripe : idempotent requests
• Slack : Incoming Webhooks
• Slack : Web API rate limits
• GitHub : validation des deliveries webhook
• GitHub : REST API rate limits
• Google : OAuth 2.0 for Google APIs

Si vous intégrez Claude Code dans des workflows d’équipe, préparez des modèles réutilisables avant le premier incident. Les checklists pratiques sont dans /products/ et l’accompagnement d’équipe dans /training/.

Après test en conditions réelles, les intégrations qui avaient dès le départ vérification de signature, idempotence, logs d’audit et environnements de test séparés étaient beaucoup plus simples à étendre. Même une petite notification Slack devient plus fiable quand un échec peut être tracé et rejoué volontairement.