gigstack Webhooks: Automatiza tu Flujo de Facturación con Eventos

Los webhooks son la forma más eficiente de mantener tu aplicación sincronizada con los eventos de facturación en gigstack. En lugar de hacer polling constante preguntando “¿hay facturas nuevas?”, gigstack te notifica cuando algo sucede: factura creada, pago recibido, cancelación completada.

Esta guía técnica te explica cómo configurar webhooks, qué eventos están disponibles y cómo procesarlos en tu aplicación.

Qué son los Webhooks

Un webhook es una llamada HTTP POST que gigstack hace a tu servidor cuando ocurre un evento. Tú defines una URL en tu aplicación (endpoint), y cada vez que se crea una factura, se cancela, o sucede cualquier evento relevante, gigstack envía los datos a ese endpoint.

Ventajas sobre polling:

Tiempo real: Recibes la notificación segundos después del evento
Eficiencia: No desperdicias recursos preguntando constantemente
Simplicidad: Tu código solo reacciona cuando hay algo que procesar

Configuración de Webhooks

Vía Panel de gigstack

En app.gigstack.pro, ve a Configuración > Webhooks. Agrega un nuevo webhook con:

URL: El endpoint en tu servidor (https://tuapp.com/webhooks/gigstack)
Eventos: Selecciona qué eventos quieres recibir
Secret: Se genera automáticamente para validar autenticidad

Vía API

POST a /webhooks:

{ "url": "https://tuapp.com/webhooks/gigstack", "events": [ "invoice.created", "invoice.cancelled", "payment.received" ] }

Eventos Disponibles

Facturas

invoice.created - Factura timbrada exitosamente
invoice.cancelled - Factura cancelada (aceptada por receptor o automática)
invoice.cancellation_pending - Cancelación enviada, esperando aceptación del receptor
invoice.cancellation_rejected - El receptor rechazó la cancelación
invoice.cancellation_expired - Venció el plazo de respuesta del receptor

Pagos y Complementos

payment.received - Pago registrado en el sistema
complement.created - Complemento de pago generado y timbrado

Clientes

client.created - Nuevo cliente registrado
client.updated - Datos de cliente actualizados
client.validation_failed - Datos fiscales no válidos ante SAT

Notas de Crédito

credit_note.created - Nota de crédito generada

Estructura del Payload

Cada webhook envía un JSON con esta estructura:

{ "id": "evt_abc123xyz", "event": "invoice.created", "timestamp": "2026-01-15T14:30:00Z", "data": { "id": "inv_123", "uuid": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890", "total": 11600, "subtotal": 10000, "taxes": 1600, "currency": "MXN", "status": "active", "client": { "id": "cli_456", "legal_name": "Empresa Cliente SA", "rfc": "ECL920318XXX" }, "items": [ { "description": "Servicio mensual", "quantity": 1, "unit_price": 10000, "total": 11600 } ], "pdf_url": "https://api.gigstack.io/invoices/inv_123/pdf", "xml_url": "https://api.gigstack.io/invoices/inv_123/xml" } }

Validación de Webhooks

Para asegurar que el webhook viene de gigstack y no de un atacante, valida la firma:

Header de firma

Cada request incluye el header: X-Gigstack-Signature

Cómo validar

Obtén el body raw del request (antes de parsear JSON)
Calcula HMAC-SHA256 del body usando tu webhook secret
Compara con el valor del header X-Gigstack-Signature
Si coinciden, el webhook es auténtico

Ejemplo en Node.js:

const crypto = require('crypto'); function validateWebhook(body, signature, secret) { const hash = crypto .createHmac('sha256', secret) .update(body) .digest('hex'); return hash === signature; }

Mejores Prácticas

1. Responde rápido

Tu endpoint debe responder con 200 en menos de 30 segundos. Procesa el webhook de forma asíncrona si tu lógica toma tiempo.

2. Implementa idempotencia

Puedes recibir el mismo webhook más de una vez (reintentos por timeout). Usa el campo id del evento para detectar duplicados.

3. Almacena antes de procesar

Guarda el webhook raw en tu base de datos antes de procesarlo. Si algo falla, tienes el dato para reprocesar.

4. Maneja errores gracefully

Si tu procesamiento falla, retorna 500 para que gigstack reintente. Solo retorna 200 si procesaste correctamente.

5. Usa HTTPS

Tu endpoint debe usar HTTPS. gigstack no envía webhooks a URLs HTTP sin cifrar.

Reintentos

Si tu endpoint no responde 200, gigstack reintenta:

1er reintento: 5 minutos después
2do reintento: 30 minutos después
3er reintento: 2 horas después
4to reintento: 8 horas después
5to reintento: 24 horas después

Después de 5 intentos fallidos, el webhook se marca como fallido. Puedes ver webhooks fallidos en el panel y reenviarlos manualmente.

Casos de Uso

Actualizar estatus en tu CRM

Cuando recibes invoice.created, actualiza el registro del cliente en tu CRM indicando que ya tiene su factura.

Notificar a tu equipo

En invoice.cancellation_pending, envía notificación a tu equipo de que hay una cancelación esperando aprobación del cliente.

Sincronizar con contabilidad

Con complement.created, registra el complemento de pago en tu sistema contable para conciliación.

Alertas de errores

En client.validation_failed, notifica al cliente que sus datos fiscales no son válidos y necesita actualizarlos.

Testing de Webhooks

Ambiente de staging

Usa tu API key de staging para generar eventos de prueba sin afectar producción.

Herramientas de desarrollo

Durante desarrollo, usa herramientas como ngrok para exponer tu localhost y recibir webhooks en tu máquina local.

Reenvío manual

En el panel de gigstack puedes reenviar cualquier webhook histórico para testing.

Monitoreo

En el panel de gigstack ves:

Historial de webhooks enviados
Estatus de cada envío (exitoso, fallido, pendiente)
Tiempo de respuesta de tu endpoint
Errores retornados por tu servidor

Implementa Webhooks Hoy

Los webhooks transforman tu integración de reactiva a proactiva. En lugar de preguntar constantemente por cambios, tu aplicación es notificada en tiempo real.

Consulta la documentación completa en docs.gigstack.io y empieza a recibir eventos de facturación en tu aplicación.