Webhook + queue : gérer 10 000 events/jour proprement

À 100 webhooks/jour, n’importe quel hack marche : un endpoint Express qui appelle 3 APIs en série, et basta. À 10 000 webhooks/jour, c’est une autre histoire. Quand un client e-commerce m’a appelé en panique parce que son Shopify perdait des commandes (le webhook timeout, retry, double-traitement, base saturée), j’ai dû refondre toute son architecture. Voici ce que j’ai mis en place et qui tourne depuis 14 mois sans une perte.

Le problème : pourquoi on ne traite pas un webhook en synchrone

Un webhook, c’est un POST HTTP qu’un service envoie à ton endpoint quand un événement se passe. Stripe, Shopify, HubSpot, GitHub, Zapier, n8n… tout le monde en envoie. Le piège : le service émetteur attend une réponse dans un délai serré (souvent 5 à 15 secondes max), sinon il considère que ton endpoint a planté.

Quand ton handler synchrone fait 4 appels API qui prennent chacun 1-3s, t’es déjà à 12s en moyenne. Et si une API ralentit, t’es mort. Le service émetteur retry. Tu traites deux fois. Tu crées un doublon dans ta DB. Tu envoies un email deux fois.

Le pattern correct, c’est :

1. Tu réponds immédiatement 200 OK (en < 500 ms idéalement)
2. Tu stockes le payload dans une queue
3. Un worker traite la queue à son rythme, avec retry intelligent, idempotence garantie

C’est de l’architecture éprouvée depuis 15 ans, mais beaucoup de devs débutants ne la mettent pas en place. Faisons-le proprement.

Le stack que j’utilise

Pour 95% de mes projets clients en 2026 :

• Express ou Hono pour l’endpoint qui reçoit les webhooks
• BullMQ comme système de queue (Node.js, basé sur Redis)
• Redis managé (Upstash, Render, ou Redis Cloud) — souvent 0-10 €/mois
• Worker dans un process séparé qui consomme la queue
• Postgres (Supabase ou Neon) pour la persistence
• Monitoring Bull Board ou Sentry

Tout en TypeScript, structuré selon le pattern décrit dans mon article TypeScript pour bots : structure de projet propre.

Pourquoi BullMQ et pas SQS/PubSub/RabbitMQ ?

• BullMQ : open-source, simple, dashboard UI gratuit, parfait pour 95% des besoins
• SQS : excellent à très haut volume (millions/jour) mais setup AWS pénible pour des projets modestes
• PubSub Google : équivalent SQS, idem
• RabbitMQ : ultra-puissant mais complexité opérationnelle élevée

À moins d’être déjà tout-AWS ou d’avoir vraiment des contraintes spécifiques, BullMQ couvre 99% des cas.

L’endpoint webhook : minimaliste et rapide

Voici l’endpoint Express type que je code. Volontairement simple :

import express from "express";
import { Queue } from "bullmq";
import crypto from "crypto";
import { env } from "@/config/env";
import { logger } from "@/core/logger";

const app = express();
const queue = new Queue("webhooks", {
  connection: { url: env.REDIS_URL },
});

// Raw body pour vérification de signature
app.use("/webhooks/stripe", express.raw({ type: "application/json" }));

app.post("/webhooks/stripe", async (req, res) => {
  const signature = req.headers["stripe-signature"] as string;
  const body = req.body.toString("utf8");

  // 1. Vérifier la signature en < 50 ms
  if (!verifyStripeSignature(body, signature, env.STRIPE_WEBHOOK_SECRET)) {
    logger.warn("Signature Stripe invalide");
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(body);

  // 2. Idempotence : si on a déjà reçu cet event ID, on accuse réception sans rien faire
  const existingJob = await queue.getJob(event.id);
  if (existingJob) {
    logger.info({ eventId: event.id }, "Event déjà en queue, ignoré");
    return res.status(200).send("Already queued");
  }

  // 3. On push dans la queue avec l'event.id comme jobId (clé de dédoublonnement)
  await queue.add(
    "stripe-event",
    { event, receivedAt: Date.now() },
    {
      jobId: event.id,
      attempts: 5,
      backoff: { type: "exponential", delay: 1000 },
      removeOnComplete: { count: 1000 },
      removeOnFail: { count: 500 },
    }
  );

  // 4. On répond 200 immédiatement (idéalement < 200 ms total)
  res.status(200).send("OK");
});

function verifyStripeSignature(body: string, header: string, secret: string): boolean {
  // implémentation HMAC SHA256, voir doc Stripe
  // ...
  return true;
}

app.listen(3000, () => logger.info("Webhook receiver up"));

Points importants :

• Vérification de signature en premier. Avant tout. Si quelqu’un essaie de forger un webhook, on l’écarte direct.
• Idempotence avec jobId: event.id. BullMQ refuse d’ajouter un job avec un jobId déjà existant. C’est ta protection gratuite contre les retries du service émetteur.
• Stockage minimal du payload. On stocke l’event entier dans la queue (Redis), pas dans Postgres. Pourquoi : c’est plus rapide, et si le worker plante, le job reste en queue.
• Retry exponentiel. 5 tentatives, 1s puis 2s puis 4s puis 8s puis 16s. Si après 16s c’est toujours rouge, on échoue (et on récupère le job dans failed pour analyse).
• Limites de rétention. removeOnComplete: { count: 1000 } garde les 1000 derniers jobs réussis pour debug. Sinon Redis explose.

Le worker : où la vraie logique se passe

Le worker est un process séparé. Tu le déploies à côté de l’endpoint, sur le même Redis, et il consomme les jobs.

import { Worker } from "bullmq";
import { env } from "@/config/env";
import { logger } from "@/core/logger";
import { handleStripeEvent } from "@/handlers/stripe";

const worker = new Worker(
  "webhooks",
  async (job) => {
    const { event } = job.data;
    logger.info({ jobId: job.id, eventType: event.type }, "Traitement event");

    switch (event.type) {
      case "checkout.session.completed":
        return await handleStripeEvent.checkoutCompleted(event.data.object);
      case "invoice.payment_succeeded":
        return await handleStripeEvent.paymentSucceeded(event.data.object);
      case "customer.subscription.deleted":
        return await handleStripeEvent.subscriptionDeleted(event.data.object);
      default:
        logger.info({ eventType: event.type }, "Event non géré, skip");
        return { skipped: true };
    }
  },
  {
    connection: { url: env.REDIS_URL },
    concurrency: 10,
    limiter: { max: 100, duration: 1000 },
  }
);

worker.on("completed", (job) => {
  logger.info({ jobId: job.id }, "Job terminé");
});

worker.on("failed", (job, err) => {
  logger.error({ jobId: job?.id, err }, "Job échoué");
});

Points clés :

• concurrency: 10 : ce worker traite jusqu’à 10 jobs en parallèle. À ajuster selon ta machine et la nature des jobs (CPU vs I/O bound).
• limiter: { max: 100, duration: 1000 } : max 100 jobs/seconde. Protège tes APIs externes contre toi-même.
• Le worker n’a aucune idée que ça vient d’un webhook. Il consomme juste des jobs. Tu peux déclencher la même logique depuis un script manuel, un test, un cron.

L’idempotence côté worker

Le jobId BullMQ protège contre les double-ajouts en queue. Mais ton handler doit ÊTRE idempotent lui aussi, parce qu’un worker peut crasher en plein milieu d’un job et le job sera reretenté.

Exemple typique pour checkout.session.completed :

async function checkoutCompleted(session: Stripe.Checkout.Session) {
  // Étape 1 : vérifier si on a déjà traité ce paiement
  const existing = await db.orders.findUnique({
    where: { stripe_session_id: session.id },
  });

  if (existing && existing.status === "fulfilled") {
    logger.info({ sessionId: session.id }, "Commande déjà fulfilled, skip");
    return { skipped: true };
  }

  // Étape 2 : créer ou mettre à jour la commande
  const order = await db.orders.upsert({
    where: { stripe_session_id: session.id },
    create: {
      stripe_session_id: session.id,
      email: session.customer_email!,
      amount: session.amount_total!,
      status: "paid",
    },
    update: { status: "paid" },
  });

  // Étape 3 : envoyer l'email (idempotent : Resend a un id de message)
  if (!order.welcomeEmailSentAt) {
    await sendWelcomeEmail(order);
    await db.orders.update({
      where: { id: order.id },
      data: { welcomeEmailSentAt: new Date() },
    });
  }

  // Étape 4 : marquer fulfilled
  await db.orders.update({
    where: { id: order.id },
    data: { status: "fulfilled" },
  });

  return { orderId: order.id };
}

Chaque action est protégée par un état stocké. Si le worker crashe entre l’étape 3 et 4, le re-run ne renverra PAS un deuxième email. C’est ça l’idempotence.

Le dimensionnement

À 10 000 events/jour, faisons les calculs :

• 10 000 / 86 400 ≈ 0,12 events/seconde en moyenne
• Mais avec une pointe x10 possible (à 9h du matin) : 1,2 events/seconde sur quelques minutes
• Si chaque job prend 2 secondes en moyenne à traiter, il faut au moins 3 workers en parallèle pour ne pas accumuler de retard

Mon dimensionnement type pour 10K events/jour :

• 1 endpoint receiver : process Node simple, 256 MB RAM suffit (il fait peu)
• 2-4 workers : process séparés ou threads, 512 MB RAM chacun
• Redis : 100 MB pour les jobs en transit + historique. Plan Upstash gratuit (10 000 commandes/jour) suffit pour de la dev. Pour la prod, prendre le plan à 10 $/mois (250k commandes/jour, latence < 5 ms).
• Postgres : selon ce que tu stockes, mais 1 GB suffit pour 1-2M de commandes

Coût total infra mensuelle : 20-40 €. Pour 10K events/jour. À comparer aux 200-500 €/mois que coûterait une “solution managée” type Make ou Workato.

Monitoring : tu dois voir ce qui se passe

Quand t’as 10K jobs/jour, tu DOIS avoir un dashboard. Sinon t’es aveugle.

Solution gratuite : Bull Board

import { createBullBoard } from "@bull-board/api";
import { BullMQAdapter } from "@bull-board/api/bullMQAdapter";
import { ExpressAdapter } from "@bull-board/express";

const serverAdapter = new ExpressAdapter();
serverAdapter.setBasePath("/admin/queues");

createBullBoard({
  queues: [new BullMQAdapter(queue)],
  serverAdapter,
});

app.use("/admin/queues", basicAuth({ users: { admin: env.ADMIN_PASSWORD } }), serverAdapter.getRouter());

Tu vas sur /admin/queues, tu vois les jobs en attente, actifs, complétés, échoués. Tu peux retry/cleaner manuellement. Indispensable.

Solution sérieuse : Sentry + alertes

En complément de Bull Board, je branche systématiquement Sentry pour capturer les erreurs et envoyer une alerte Slack quand un job échoue plus de 3 fois.

worker.on("failed", async (job, err) => {
  if (job && job.attemptsMade >= 3) {
    Sentry.captureException(err, {
      tags: { jobName: job.name, jobId: job.id },
      extra: { data: job.data },
    });
    await sendSlackAlert(`Job ${job.id} a échoué ${job.attemptsMade} fois : ${err.message}`);
  }
});

Pour les services qui hébergent ces workers, j’ai écrit un comparatif des plateformes d’hébergement et de scheduling : cron jobs vs n8n vs GitHub Actions. Pour les workers continus, je recommande Railway, Fly.io ou un VPS classique avec PM2/systemd.

Le problème spécifique des webhooks Stripe / Shopify / GitHub

Chacun a ses subtilités :

Stripe : retry pendant 3 jours, attend un 200 dans 30s, dédoublonne via Stripe-Signature + ton check d’idempotence sur event.id. Liste des events à activer : juste ceux dont tu as besoin, pas “all events” (sinon t’es noyé).

Shopify : retry pendant 48h, mais espacement croissant agressif (peut sauter directement à plusieurs heures). Si ton endpoint répond > 5 secondes, Shopify considère l’echec. Toujours répondre vite. Header X-Shopify-Webhook-Id à utiliser pour l’idempotence.

GitHub : ne retry PAS par défaut. Si tu rates un event, c’est perdu (sauf si tu actives “redeliver” manuellement dans l’UI). Donc particulièrement important de bien gérer ton receiver pour ne JAMAIS renvoyer un 4xx/5xx involontaire.

HubSpot : retry 10 fois sur 24h. Très tolérant. Mais les events sont batched (jusqu’à 100 dans un même POST), donc ton endpoint doit savoir traiter un array.

Cas vécu : la migration d’un client e-commerce

Le client recevait :

• 6 000 webhooks Shopify/jour (commandes, refunds, abandons de panier)
• 2 000 webhooks Stripe/jour (paiements, refunds, disputes)
• 1 500 webhooks Klaviyo/jour (events email)

Total : ~10 000 events/jour. Endpoint Express monolithique, fait tout en synchrone, perd 2-3% des events à cause des timeouts.

Ce que j’ai mis en place :

1. Receiver Hono ultra-léger (40 MB RAM) qui vérifie signature et push en queue
2. Worker BullMQ avec 8 workers en parallèle, hébergé sur Fly.io (10 €/mois)
3. Redis Upstash (10 €/mois)
4. Bull Board accessible en interne
5. Sentry pour les alertes
6. Postgres Supabase pour la persistence

Résultat 14 mois après :

• 0 event perdu
• Latence p99 du receiver : 89 ms (vs 4-15s avant)
• Worker traite la pointe matinale (700 events/min) sans broncher
• Coût infra total : 32 €/mois
• Le client a divisé par 3 son taux de “commande paid mais pas fulfilled”

Erreurs à éviter

1. Pas vérifier la signature du webhook. Une URL /webhooks/stripe publique peut être appelée par n’importe qui. Sans signature, tu peux te faire injecter des fake events. Catastrophe garantie.

2. Utiliser la même DB que ton app principale pour la queue. Une queue, c’est de l’écriture-lecture-suppression intensive. Si tu fais ça dans ton Postgres app, ton main app va ralentir. Toujours Redis dédié pour les queues.

3. Pas d’idempotence côté worker. “BullMQ dédoublonne déjà avec jobId” - oui, à l’entrée. Mais entre deux retries d’un même jobId qui plante au milieu, ton handler doit gérer.

4. Tout faire dans le receiver. Le receiver doit faire 3 choses : vérifier signature, dédoublonner, queuer. Point. Pas de “tant que j’y suis, je vais juste mettre à jour la DB”. Le pattern doit être inviolable.

5. Pas de DLQ (dead letter queue). Quand un job échoue après ses retries, où va-t-il ? Si tu fais removeOnFail: true, il disparaît et tu ne le sauras jamais. Toujours removeOnFail: { count: 500 } minimum pour pouvoir investiguer.

6. Ignorer les events en double. Stripe peut envoyer 2x le même event si ton premier 200 met trop de temps à arriver. Si tu n’es pas idempotent, tu vas créditer 2x ton client. Ça coûte plus cher qu’un dev senior 1 mois.

Quand monter en gamme

Au-delà de 100 000 events/jour, le pattern reste valable mais il faut :

• Plusieurs receivers derrière un load balancer
• Plusieurs workers répartis sur plusieurs machines
• Redis cluster (vrai cluster, pas juste un master)
• Monitoring poussé (Datadog, Grafana)
• Tests de charge réguliers

Au-delà de 1M events/jour, regarde sérieusement SQS + Lambda ou un Kafka + workers. Tu sors du périmètre BullMQ.

Conclusion

Pour 10 000 events/jour, BullMQ + Redis + workers TypeScript est la stack qui marche, qui coûte 30 €/mois en infra, et qui dort tranquille pendant 18 mois. Cette architecture, je la déploie au moins une fois par mois sur un nouveau projet client. Elle est solide, testée, simple à maintenir.

Si tu es face à un problème de webhooks qui se perdent, de doublons en base, ou d’une explosion de volume que ton archi actuelle ne supporte plus, je peux concevoir et déployer cette architecture pour toi. C’est exactement ce que je vends dans un workflow avancé ou dans une architecture complète selon l’ampleur. On peut commencer par un audit gratuit de 45 min pour cartographier ton flux actuel et identifier les fragilités.