Skip to content

Shinkansen · Payout metadata (→ BigQuery)

De punta a punta: del webhook de Shinkansen (notificación tipo metadata) a la tabla cruda shinkansen.shinkansen_metadata en BigQuery. Es la rama warehouse del mismo topic del que también cuelga el proceso CEP de LoanPro.

¿Llegaste hasta acá desde…?

Usa esta tabla para entrar en sentido inverso (lo que ves → de dónde sale):

Si ves… Eso sale de… La lógica está en…
La tabla shinkansen.shinkansen_metadata en BigQuery / Metabase solvento-data-prod.shinkansen.shinkansen_metadata (RAW) Ingesta (sin lógica de negocio); ver "Paso a paso"
El comprobante de pago (receipt URL) escrito en un loan de LoanPro Otro consumidor del mismo topic ver shinkansen-loanpro-cep.md (rama writeback a la app)
Un evento de Shinkansen que no llega a ninguna tabla Clasificación del webhook webhook_shinkansen → cloud_run/main.py (detect_event_type)

Resumen

Campo Valor
Origen Webhook de Shinkansen, notificación metadata (document.notifications[].notification_type == "metadata")
Patrón Event-driven (Cloud Run clasifica → Pub/Sub → Dataflow → BigQuery)
Tabla RAW solvento-data-prod.shinkansen.shinkansen_metadata
Frecuencia Streaming
Criticidad 🟡 Media
Dueño Martin (data eng)
Repos webhook_shinkansen · templates-dataflow

Diagrama de linaje

graph LR
    SHK[["📨 Shinkansen<br/>webhook (metadata)"]]
    CR["Cloud Run<br/>webhook-shinkansen-inline-prod<br/><i>clasifica por tipo</i>"]
    TOP(["Pub/Sub<br/>shinkansen-payout-metadata-prod"])
    SUB(["sub<br/>shinkansen-payout-metadata-prod-sub"])
    DF["Dataflow<br/>shinkansen-metadata-webhook-prod-20260112-200033"]
    BQ[("solvento-data-prod<br/>shinkansen.shinkansen_metadata")]
    CEP["Cloud Run CEP<br/>(otro consumidor · writeback LoanPro)"]
    MB["Metabase / análisis"]

    SHK -->|HTTP| CR -->|"SHINKANSEN_PAYOUT_METADATA_TOPIC"| TOP
    TOP -->|"sub warehouse"| SUB --> DF --> BQ --> MB
    TOP -.->|"fan-out · otra sub"| CEP

    classDef src fill:#fde68a,stroke:#b45309,color:#000;
    classDef store fill:#bfdbfe,stroke:#1e40af,color:#000;
    class SHK src;
    class BQ store;

Paso a paso

  1. Shinkansen emite un webhook por cada notificación de payout. Cuando es de tipo metadata, trae receipt_url y tracking_key dentro de document.notifications[].
  2. Cloud Run webhook-shinkansen-inline-prod (webhook_shinkansen, cloud_run/main.py) recibe el POST en /shinkansen (o /webhook/shinkansen), clasifica el evento con detect_event_type (payout_metadata, payout_results, response) y publica el de tipo metadata en el topic configurado en SHINKANSEN_PAYOUT_METADATA_TOPIC.
  3. Pub/Sub desacopla: topic shinkansen-payout-metadata-prod con fan-out (dos consumidores, ver abajo).
  4. Suscripción shinkansen-payout-metadata-prod-sub alimenta el Dataflow shinkansen-metadata-webhook-prod-20260112-200033 (templates-dataflow, carpeta shinkansen-metadata-webhook; INPUT_SUBSCRIPTION y OUTPUT_TABLE en su prod.env).
  5. BigQuery: el Dataflow escribe el dato crudo en solvento-data-prod.shinkansen.shinkansen_metadata (OUTPUT_TABLE=solvento-data-prod:shinkansen.shinkansen_metadata). No hay lógica de negocio en la ingesta.

Fan-out — no confundir con el CEP: el mismo topic shinkansen-payout-metadata-prod tiene otro consumidor, el proceso CEP de LoanPro, que toma el receipt_url y lo escribe de vuelta en el loan de LoanPro (no carga BigQuery). Ese flujo está documentado aparte en shinkansen-loanpro-cep.md. Esta ficha es solo la rama warehouse → BigQuery.

Tablas que alimenta

Tabla Contenido Job que la carga
solvento-data-prod.shinkansen.shinkansen_metadata Metadata cruda de notificaciones de payout de Shinkansen Dataflow shinkansen-metadata-webhook-prod-20260112-200033

Consumo aguas abajo

  • Metabase / análisis de payouts leen directamente de solvento-data-prod.shinkansen.shinkansen_metadata.
  • Si existe una capa de staging sobre esta tabla, vive en dbt-analytics (models/staging/shinkansen — (confirmar)). Por criticidad media no se rastrean los modelos aquí.

Si falla 🛠️

Impacto: deja de actualizarse shinkansen.shinkansen_metadata en BigQuery (queda desactualizada la metadata de payouts para análisis). No afecta a la rama CEP (es otra suscripción del mismo topic). Pub/Sub retiene los mensajes hasta que el Dataflow los consuma.

Síntoma Dónde mirar Acción
No llegan eventos nuevos a ninguna tabla de Shinkansen Logs Cloud Run webhook-shinkansen-inline-prod Si fue un deploy → rollback; verificar que SHINKANSEN_PAYOUT_METADATA_TOPIC esté configurado
Llega al topic pero la RAW no avanza Dataflow shinkansen-metadata-webhook-prod-…: watermark del job; backlog de la sub shinkansen-payout-metadata-prod-sub Transitorios se recuperan solos consumiendo la misma suscripción; si hay duda, relanzar/escalar
Eventos clasificados como UNKNOWN Logs del webhook (detect_event_type) Revisar si Shinkansen cambió el esquema; ajustar la detección en cloud_run/main.py
Datos en BQ pero "raros" en Metabase Capa dbt en dbt-analytics (si aplica) Revisar la transformación en el repo, no la ingesta

Escalación: lógica SQL / Metabase → Diego · resto (ingesta, Cloud Run, Dataflow, Pub/Sub) → Martin.

Enlaces

Última actualización: 2026-06-21 · Si cambia el flujo o el esquema del webhook, actualizar esta ficha en el mismo MR.