Skip to content

Shinkansen · Payout results (→ BigQuery)

De punta a punta: del webhook de Shinkansen (evento con payout_order_results) a la tabla cruda shinkansen.shinkansen_payout_results en BigQuery. Comparte el Cloud Run clasificador con la metadata, pero usa su propio topic (sin fan-out).

¿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_payout_results en BigQuery / Metabase solvento-data-prod.shinkansen.shinkansen_payout_results (RAW) Ingesta (sin lógica de negocio); ver "Paso a paso"
Un resultado de payout que no aparece en la tabla Clasificación del webhook webhook_shinkansen → cloud_run/main.py (detect_event_type → payout_results)

Resumen

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

Diagrama de linaje

graph LR
    SHK[["📨 Shinkansen<br/>webhook (payout_results)"]]
    CR["Cloud Run<br/>webhook-shinkansen-inline-prod<br/><i>clasifica por tipo</i>"]
    TOP(["Pub/Sub<br/>shinkansen-payout-results-prod"])
    SUB(["sub<br/>shinkansen-payout-results-prod-sub"])
    DF["Dataflow<br/>shinkansen-payout-results-webhook-prod-20260112-195635"]
    BQ[("solvento-data-prod<br/>shinkansen.shinkansen_payout_results")]
    MB["Metabase / análisis"]

    SHK -->|HTTP| CR -->|"SHINKANSEN_PAYOUT_RESULTS_TOPIC"| TOP --> SUB --> DF --> BQ --> MB

    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 actualización de payout. Cuando trae document.payout_order_results[], es un evento de resultados de payout.
  2. Cloud Run webhook-shinkansen-inline-prod (webhook_shinkansen, cloud_run/main.py) recibe el POST en /shinkansen, lo clasifica con detect_event_type y, al detectar payout_results, lo publica en el topic configurado en SHINKANSEN_PAYOUT_RESULTS_TOPIC.
  3. Pub/Sub desacopla: topic shinkansen-payout-results-prod → suscripción shinkansen-payout-results-prod-sub.
  4. Dataflow shinkansen-payout-results-webhook-prod-20260112-195635 (templates-dataflow, carpeta shinkansen-payout-results-webhook; INPUT_SUBSCRIPTION=…/shinkansen-payout-results-prod-sub y OUTPUT_TABLE en su prod.env) consume la suscripción.
  5. BigQuery: el Dataflow escribe el dato crudo en solvento-data-prod.shinkansen.shinkansen_payout_results (OUTPUT_TABLE=solvento-data-prod:shinkansen.shinkansen_payout_results). No hay lógica de negocio en la ingesta.

El mismo Cloud Run clasifica los tres tipos de evento (payout_metadata, payout_results, response); este proceso es la rama payout_results. La rama payout_metadata está en shinkansen-payout-metadata.md.

Tablas que alimenta

Tabla Contenido Job que la carga
solvento-data-prod.shinkansen.shinkansen_payout_results Resultados crudos de payout orders de Shinkansen Dataflow shinkansen-payout-results-webhook-prod-20260112-195635

Consumo aguas abajo

  • Metabase / análisis de resultados de payout leen directamente de solvento-data-prod.shinkansen.shinkansen_payout_results.
  • 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_payout_results en BigQuery (queda desactualizado el análisis de resultados de dispersiones). 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_RESULTS_TOPIC esté configurado
Llega al topic pero la RAW no avanza Dataflow shinkansen-payout-results-webhook-prod-…: watermark; backlog de la sub shinkansen-payout-results-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.