NexoSaaS — Hookdeck Event Gateway

Arquitectura de webhooks con entrega garantizada · Diseñado por CULTIVA IA

340 clientes activos
● Gateway activo
⚠️

Incidente Black Friday 2025

Pico de tráfico en Stripe saturó el servidor propio. Sin cola ni reintentos, los eventos se perdieron sin posibilidad de recuperación automática.

120 eventos perdidos
37 suscripciones corruptas
8h recuperación manual
Observabilidad — últimas 24h (post-Hookdeck)
Eventos recibidos
2.847
↑ +18% vs. semana anterior
Tasa de entrega
99.97%
↑ desde 94.3% (sin Hookdeck)
Eventos reintentados
12
100% entregados en reintento
Latencia p95 gateway
43ms
overhead mínimo
Arquitectura — flujo de webhooks
💳
Stripe
pagos · suscripciones
🛍️
Shopify
pedidos clientes
🐙
GitHub
deploys CI/CD
HOOKDECK EVENT GATEWAY
Hookdeck
events.hookdeck.com/e/src_*
Ingesta garantizada
Cola durable en memoria
Reintentos automáticos (50x)
Backoff exponencial
Rate limiting configurable
Pausa durante deploys
Filtrado por payload
Dashboard + alertas Slack
🚀
NexoSaaS API
Node.js + Express · Railway
POST /webhooks/stripe
POST /webhooks/shopify
POST /webhooks/github
Sin Hookdeck vs. Con Hookdeck

Sin Hookdeck — código defensivo

ANTES
1
Stripe envía webhook al servidor de NexoSaaS directamente
2
Handler responde en <5s o Stripe marca como fallido
⚠ Timeout si hay carga o DB lenta
3
Hay que gestionar cola propia (BullMQ/SQS) para no perder eventos
⚠ Infraestructura adicional a mantener
4
Pico de tráfico → 120 eventos perdidos, 37 suscripciones corruptas
⚠ Sin replay, recuperación manual

Con Hookdeck — lógica de negocio pura

AHORA
1
Stripe envía webhook a Hookdeck (ingesta inmediata y garantizada)
✓ Nunca pierde eventos aunque el servidor esté caído
2
Hookdeck encola y entrega a NexoSaaS API a ritmo configurable
✓ Rate limit: 50 req/s máximo (protección spikes)
3
Handler solo procesa lógica de negocio, sin cola propia
✓ 60 segundos para procesar sin timeout del proveedor
4
Fallo → reintento automático (hasta 50x, backoff exponencial)
✓ Replay en dashboard o bulk via API
Log de eventos — últimos 30 min
customer.subscription.updated
stripe
hace 2m
invoice.payment_succeeded
stripe
hace 5m
orders/create
shopify
hace 8m
reintento 1/50
orders/create
shopify
hace 9m
push (deploy producción)
github
hace 14m
customer.subscription.created
stripe
hace 18m
invoice.payment_failed
stripe
hace 22m
products/update (bulk ×47)
shopify
hace 29m
Handler NexoSaaS — solo lógica de negocio
webhooks/stripe.js
// Hookdeck verifica firma y encola — nosotros
// solo procesamos lógica de negocio

app.post('/webhooks/stripe', async (req, res) => {
  const event = JSON.parse(req.body.toString());

  // ✅ 60s para procesar (Hookdeck no timea)
  switch (event.type) {
    case 'customer.subscription.updated':
      await updateSubscription(event.data.object);
      await syncBillingToPostgres(event.data.object);
      break;

    case 'invoice.payment_failed':
      await flagAccountPastDue(event.data.object);
      await sendDunningEmail(event.data.object);
      break;
  }

  // ✅ Hookdeck reintenta si retorna != 2xx
  res.json({ received: true });
});
Setup local en 3 comandos
Paso 1 — Tunnel Stripe
npx hookdeck-cli listen 3000 stripe --path /webhooks/stripe
Crea URL pública que apunta a tu servidor local. Sin cuenta. Perfecto para desarrollo.
Paso 2 — Tunnel Shopify
npx hookdeck-cli listen 3000 shopify --path /webhooks/shopify
Cada proveedor tiene su propio source en Hookdeck con filtros independientes.
Paso 3 — Verificación firma
npx skills add hookdeck/webhook-skills --skill hookdeck-event-gateway-webhooks
Instala verificación de x-hookdeck-signature en Express/Next.js/FastAPI.