---
id: "INT-006"
title: "Integracion Webhooks Outbound"
type: "Integration"
status: "Implemented"
priority: "P1"
provider: "BullMQ/Redis"
category: "Messaging"
multi_tenant: true
version: "1.0.0"
created_date: "2026-01-07"
updated_date: "2026-01-10"
---

# INT-006: Webhooks Outbound

## Metadata
| Campo | Valor |
|-------|-------|
| Codigo | INT-006 |
| Proveedor | BullMQ + Redis |
| Tipo | Webhooks |
| Estado | Implementado |
| Multi-tenant | Si |
| Fecha integracion | 2026-01-10 |

---

**Documentacion completa:** Ver [SAAS-010-webhooks.md](../01-modulos/SAAS-010-webhooks.md)

## Resumen

Sistema de webhooks outbound para notificar eventos a sistemas externos.

## Tecnologia

- BullMQ para cola de procesamiento
- Redis como backend de cola
- Firma HMAC-SHA256 de payloads

## Caracteristicas

- Eventos de suscripcion, usuarios, tenants, etc.
- Reintentos automaticos con backoff
- Logs de entrega
- Configuracion por tenant

## Eventos Disponibles

- subscription.created/updated/cancelled
- user.created/updated/deleted
- tenant.created/updated
- invoice.paid/failed
- Y mas...

## Configuracion

```env
REDIS_HOST=localhost
REDIS_PORT=6379
WEBHOOK_MAX_RETRIES=5
WEBHOOK_RETRY_DELAY=60000
```

## Rate Limits
| Limite | Valor | Accion si excede |
|--------|-------|------------------|
| Webhooks/min | 1000 por tenant | Cola de espera |

## Manejo de Errores
| Codigo | Descripcion | Accion |
|--------|-------------|--------|
| 400 | Bad Request | Log + no retry |
| 401 | Unauthorized | Renovar credenciales |
| 429 | Rate Limited | Backoff exponencial |
| 500 | Server Error | Retry con backoff (max 5 intentos) |
| Timeout | Conexion agotada | Retry con backoff |

## Fallbacks

### Dead Letter Queue (DLQ)

| Intento | Delay | Accion si falla |
|---------|-------|-----------------|
| 1 | Inmediato | Encolar retry |
| 2 | 1 minuto | Encolar retry |
| 3 | 5 minutos | Encolar retry |
| 4 | 15 minutos | Encolar retry |
| 5 | 1 hora | Mover a DLQ |

### Procesamiento DLQ

- Revision manual requerida para webhooks en DLQ
- Alerta a Slack/Email si DLQ > 10 items
- Expiracion automatica: 7 dias
- Dashboard Bull Board para visualizacion

### Retry Strategy

```typescript
{
  attempts: 5,
  backoff: {
    type: 'exponential',
    delay: 60000  // 1min, 2min, 4min, 8min, 16min
  },
  removeOnComplete: { age: 86400 },  // 24h
  removeOnFail: false  // Mantener en DLQ
}
```

### Monitoreo DLQ

| Metrica | Descripcion | Alerta |
|---------|-------------|--------|
| DLQ size | Webhooks fallidos | >10 items |
| DLQ age | Tiempo en DLQ | >24h |
| Retry rate | Tasa de reintentos | >10% |

## Multi-tenant
- Credenciales: Por tenant (cada tenant configura sus endpoints y secrets)
- Configuracion: Por tenant via tenant_config
- Aislamiento: Prefijo tenant_id en todas las operaciones

## Testing
### Sandbox/Test Mode
- Usar servicios como webhook.site para testing
- Logs detallados de entrega en desarrollo
- Fixtures disponibles para testing unitario

## Monitoreo
| Metrica | Descripcion | Alerta |
|---------|-------------|--------|
| Latencia | Tiempo de respuesta | >2s |
| Errores | Tasa de errores | >1% |
| Disponibilidad | Uptime del servicio | <99.9% |

## Referencias

- Modulo relacionado: SAAS-010-webhooks.md

---

**Ultima actualizacion:** 2026-01-10
**Version:** 1.0.0