Skip to content

Webhooks

Los webhooks son endpoints HTTP que reciben eventos y notificaciones de sistemas externos en la arquitectura de data engineering de Solvento.

Descripción

Los webhooks permiten que sistemas externos notifiquen al sistema de Solvento cuando ocurren eventos relevantes. Son endpoints HTTP que reciben payloads y los procesan para integrarlos en el flujo de datos.

Flujo de Datos

graph TB
    subgraph externos["Sistemas Externos"]
        Webhooks[Webhooks Externos]
    end

    subgraph ingesta["Ingesta"]
        CloudRun[Cloud Run<br/>Webhook Receiver]
    end

    subgraph mensajeria["Mensajería"]
        PubSub[Pub/Sub<br/>Topic]
    end

    subgraph procesamiento["Procesamiento"]
        Dataflow[Dataflow<br/>Pipeline]
    end

    subgraph almacenamiento["Almacenamiento"]
        BigQuery[BigQuery]
    end

    Webhooks -->|"HTTP POST"| CloudRun
    CloudRun -->|"Publica eventos"| PubSub
    PubSub -->|"Consume mensajes"| Dataflow
    Dataflow -->|"Escribe datos procesados"| BigQuery

Flujo Principal de Webhooks

El flujo principal de webhooks en Solvento sigue este patrón:

  1. Recepción: Los webhooks externos llegan a un servicio Cloud Run
  2. Derivación: Cloud Run procesa y publica los eventos a Pub/Sub
  3. Procesamiento: Dataflow consume los mensajes de Pub/Sub
  4. Almacenamiento: Dataflow transforma y escribe los datos a BigQuery

Fuentes de Webhooks Activas

Webhooks de Syntage

  • Origen: Syntage (sistema externo)
  • Handler: Cloud Run (Syntage Handler)
  • Destino: Múltiples colas Pub/Sub → Dataflow Templates → BigQuery (data-prod)

Webhooks de Toku

  • Origen: Toku (sistema de pagos)
  • Handler: Cloud Run (Toku Handler)
  • Destino: Pub/Sub → Dataflow Templates → BigQuery (data-prod)

Toku en arquitectura de webhooks

Los webhooks de Toku usan la misma arquitectura estándar que Syntage: Cloud Run → Pub/Sub → Dataflow → BigQuery.

Recursos

Webhook Endpoints

Los endpoints HTTP que reciben webhooks. Documenta aquí los endpoints principales:

Cloud Run Service: Webhook Receiver

  • Servicio: Cloud Run que recibe webhooks externos
  • Función: Recibe webhooks, valida payloads y publica a Pub/Sub
  • Pub/Sub Topic: Topic destino para eventos de webhooks
  • Formato: JSON payloads de sistemas externos

Agregar URL específica del servicio y topic de Pub/Sub

Configuraciones Relevantes

Autenticación

  • API Keys: Validación mediante API keys en headers o query params
  • HMAC Signatures: Validación mediante firmas HMAC
  • Bearer Tokens: Validación mediante tokens Bearer
  • Custom Headers: Validación mediante headers personalizados

Especificar método de autenticación por endpoint

Rate Limiting

  • Límites de rate para prevenir abuso

Timeout

  • Timeout para procesamiento de webhooks

Retry Logic

  • Estrategias de reintento para webhooks fallidos

Relaciones con Otros Componentes

Receptores de Webhooks

  • Cloud Functions: Funciones HTTP que reciben webhooks
  • Cloud Run: Servicios HTTP que reciben webhooks

Procesamiento

  • Pub/Sub: Eventos de webhooks publicados a topics
  • Cloud Storage: Archivos o payloads almacenados
  • BigQuery: Datos estructurados de webhooks almacenados

Patrones de Uso

Event Notification

Recepción de notificaciones de eventos de sistemas externos.

Data Sync

Sincronización de datos cuando sistemas externos notifican cambios.

Real-time Integration

Integración en tiempo real mediante webhooks.

Acknowledgment

Confirmación de recepción de webhooks a sistemas externos.

Ejemplos de Implementación

Webhook con Cloud Functions

from flask import Flask, request, jsonify
from google.cloud import pubsub_v1
import hmac
import hashlib

app = Flask(__name__)

def verify_webhook_signature(payload, signature, secret):
    """Verifica la firma HMAC del webhook"""
    expected_signature = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected_signature)

@app.route('/webhook/external-system', methods=['POST'])
def handle_webhook():
    """Maneja webhook de sistema externo"""
    payload = request.get_data(as_text=True)
    signature = request.headers.get('X-Signature')

    # Verificar autenticación
    secret = get_secret('webhook-secret')
    if not verify_webhook_signature(payload, signature, secret):
        return jsonify({'error': 'Invalid signature'}), 401

    # Procesar payload
    data = request.get_json()

    # Publicar a Pub/Sub
    publisher = pubsub_v1.PublisherClient()
    topic_path = publisher.topic_path('solvento-data-prod', 'webhook-events')
    publisher.publish(topic_path, payload.encode('utf-8'))

    return jsonify({'status': 'received'}), 200

Webhook con Cloud Run

from flask import Flask, request, jsonify
from google.cloud import bigquery

app = Flask(__name__)

@app.route('/webhook/data-ingestion', methods=['POST'])
def handle_data_webhook():
    """Maneja webhook de ingesta de datos"""
    data = request.get_json()

    # Validar datos
    if not validate_payload(data):
        return jsonify({'error': 'Invalid payload'}), 400

    # Escribir a BigQuery
    client = bigquery.Client(project='solvento-adv-analytics-prod')
    table = client.get_table('dataset.webhook_data')
    client.insert_rows_json(table, [data])

    return jsonify({'status': 'processed'}), 200

Seguridad

Validación de Payloads

  • Validación de estructura y contenido de payloads
  • Sanitización de datos de entrada

Autenticación

  • Verificación de firmas y tokens
  • Validación de origen de requests

Rate Limiting

  • Límites de requests por IP o por sistema
  • Prevención de ataques DDoS

Monitoreo y Métricas

  • Request Rate: Tasa de webhooks recibidos
  • Success Rate: Tasa de procesamiento exitoso
  • Latency: Tiempo de procesamiento
  • Errors: Errores y fallos en procesamiento
  • Authentication Failures: Fallos de autenticación

Referencias