Webhooks - Documentación de API - iloveQR

Documentación de API

Webhooks

Recibe notificaciones en tiempo real cuando ocurren eventos en tu organización. Los webhooks te permiten construir integraciones reactivas que responden inmediatamente a los escaneos de códigos QR y otros eventos.

En tiempo real

Recibe notificaciones al instante cuando ocurren eventos, sin necesidad de sondear

Seguro

Las firmas HMAC verifican que los webhooks provienen de iloveQR

Confiable

Reintentos automáticos con retroceso exponencial para entregas fallidas

Configurando Webhooks

Configura webhooks a través del panel o API para comenzar a recibir eventos.

Crea un endpoint de webhook

Configura un endpoint HTTPS en tu servidor para recibir las cargas útiles de los webhooks.

Registra el webhook

Agrega la URL de tu endpoint y selecciona a qué eventos suscribirte.

Verifica las firmas

Implementa la verificación de firmas para asegurar que las cargas útiles sean auténticas.

Registrar Webhook

curl -X POST \
  "https://api.iloveqr.com/api/v1/organizations/org_abc123/webhooks" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/iloveqr",
    "events": ["qr.scanned", "qr.created", "qr.updated"],
    "secret": "your_webhook_secret"
  }'

Eventos de Webhook

Suscríbete a los eventos que necesitas. Cada tipo de evento tiene una estructura de carga útil específica.

Eventos de Código QR

qr.createdSe creó un nuevo código QR

qr.updatedSe actualizó un código QR

qr.deletedSe eliminó un código QR

qr.scannedSe escaneó un código QR

qr.archivedSe archivó un código QR

qr.restoredSe restauró un código QR del archivo

Eventos de Suscripción

subscription.createdSe creó una nueva suscripción

subscription.updatedSe actualizó una suscripción

subscription.cancelledSe canceló una suscripción

subscription.payment_succeededUn pago fue exitoso

subscription.payment_failedUn pago falló

Eventos de Equipo

member.joinedUn miembro se unió a la organización

member.leftUn miembro dejó la organización

member.role_changedSe cambió el rol de un miembro

Carga Útil de Webhook

Todas las cargas útiles de los webhooks siguen una estructura consistente con metadatos de eventos y datos.

Ejemplo: Evento qr.scanned

{
  "id": "evt_1a2b3c4d5e6f",
  "event": "qr.scanned",
  "createdAt": "2024-01-15T14:30:00Z",
  "organizationId": "org_abc123",
  "data": {
    "qrCodeId": "qr_xyz789",
    "qrCodeName": "Product Landing Page",
    "shortCode": "xyz789",
    "destinationUrl": "https://example.com/product",
    "scan": {
      "id": "scan_123abc",
      "timestamp": "2024-01-15T14:30:00Z",
      "location": {
        "country": "US",
        "city": "New York",
        "latitude": 40.7128,
        "longitude": -74.0060
      },
      "device": {
        "type": "mobile",
        "os": "iOS",
        "browser": "Safari"
      },
      "isUnique": true
    }
  }
}

Ejemplo: Evento qr.created

{
  "id": "evt_7g8h9i0j1k2l",
  "event": "qr.created",
  "createdAt": "2024-01-15T10:00:00Z",
  "organizationId": "org_abc123",
  "data": {
    "qrCode": {
      "id": "qr_newcode",
      "type": "URL",
      "name": "New Campaign QR",
      "shortUrl": "https://ilqr.co/newcode",
      "destinationUrl": "https://example.com/campaign",
      "createdBy": "user_abc123"
    }
  }
}

Verificando Webhooks

Siempre verifica las firmas de los webhooks para asegurar que la carga útil provino de iloveQR y no fue alterada en tránsito.

Encabezado de Firma

Cada solicitud de webhook incluye un encabezado X-Webhook-Signature que contiene una firma HMAC-SHA256 del cuerpo de la solicitud.

Ejemplo de Verificación en Node.js

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler
app.post('/webhooks/iloveqr', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifyWebhookSignature(payload, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process the webhook
  const event = req.body;
  console.log('Received event:', event.event);

  res.status(200).send('OK');
});

Ejemplo de Verificación en Python

import hmac
import hashlib

def verify_webhook_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

# In your Flask handler
@app.route('/webhooks/iloveqr', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Webhook-Signature')
    payload = request.get_data()

    if not verify_webhook_signature(payload, signature, WEBHOOK_SECRET):
        return 'Invalid signature', 401

    event = request.get_json()
    print(f"Received event: {event['event']}")

    return 'OK', 200

Mejores Prácticas

Responde rápidamente

Devuelve una respuesta 2xx dentro de los 5 segundos. Procesa los webhooks de manera asíncrona si tu manejo toma más tiempo.

Maneja duplicados

Almacena el ID del evento y verifica duplicados. Los webhooks pueden ser entregados más de una vez en casos raros.

Usa HTTPS

Siempre usa endpoints HTTPS. No entregamos webhooks a URLs HTTP.

Monitorea fallos

Configura monitoreo para fallos en la entrega de webhooks. Revisa los registros de webhooks en el panel para depuración.

Política de Reintentos

Si tu endpoint devuelve un error o no responde, automáticamente reintentamos la entrega con retroceso exponencial:

Intento	Retraso
1er reintento	1 minuto
2do reintento	5 minutos
3er reintento	30 minutos
4to reintento	2 horas
5to reintento (final)	24 horas

Nota: Después de 5 intentos fallidos, el webhook se marca como fallido y dejamos de reintentar. Recibirás una notificación por correo electrónico sobre la falla.

Próximos Pasos

¿Listo para comenzar? Explora más recursos: