Segment

Introducción

La integración con Segment envía eventos de Dodo Payments a la HTTP Tracking API de Segment como llamadas Track e Identify. Segment reenvía los datos de pagos, suscripciones y clientes a las herramientas de análisis, marketing y almacenamiento de datos conectadas a tu espacio de trabajo, desde un catálogo de más de 300 destinos.

Esta integración requiere la Write Key de una fuente HTTP API en tu espacio de trabajo de Segment. También necesitas acceso a Developer → Webhooks en el dashboard de Dodo Payments.

Comenzando

Open the Webhook Section

En el panel de Dodo Payments, ve a Developer → Webhooks y haz clic en Add endpoint.

Add endpoint dialog with Segment selected in the Integration dropdown and the How to connect Segment steps

Select Segment

En Integración, selecciona Segment. El dashboard completa la URL del endpoint y el código de transformación para Segment.

Enter Write Key

En Segment, ve a Connections → Sources y abre o crea una fuente HTTP API. Copia la Write Key de la configuración de la fuente y pégala en API key.

Select Events

En Subscribed events, selecciona solo los eventos que gestiona tu transformación. Los ejemplos de esta página usan payment.succeeded, subscription.active y subscription.cancelled.

Configure Transformation

En Transformation code, edita el handler para dar formato a los eventos para la API Track o Identify de Segment. Empieza con los ejemplos.

Test & Create

En Test this code, selecciona un tipo de evento y haz clic en Simulate para previsualizar la llamada a Segment. Luego haz clic en Create endpoint.

Switch to Basic Authentication

Dodo Payments envía el valor de API key como un bearer token, pero la HTTP API de Segment acepta una Write Key mediante autenticación Basic o un campo writeKey en el cuerpo. Justo después de crear el endpoint, abre su pestaña Advanced. En Custom headers, introduce un nuevo valor en la fila oculta Authorization: Basic, un espacio y la codificación Base64 de tu Write Key con dos puntos al final. Luego haz clic en Save. Por ejemplo, echo -n 'YOUR_WRITE_KEY:' | base64 imprime el valor codificado.

Done

Los eventos suscritos ahora llegan a Segment, que los reenvía a tus destinos conectados.

Ejemplos de código de transformación

Cada handler establece webhook.url en un endpoint de la API de Segment y reemplaza webhook.payload con la llamada. Los importes de Dodo Payments están en la unidad monetaria más pequeña, por lo que los ejemplos los dividen entre 100. Para monedas sin decimales, como JPY y KRW, usa el importe tal cual.

Registrar eventos de pago con Track

Registra un evento Payment Completed cuando un pago se complete correctamente:

track_payments.js

function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.url = "https://api.segment.io/v1/track";
    webhook.payload = {
      userId: p.customer.customer_id,
      event: "Payment Completed",
      properties: {
        amount: (p.total_amount / 100).toFixed(2),
        currency: p.currency || "USD",
        payment_method: p.payment_method || "unknown",
        payment_id: p.payment_id,
        customer_email: p.customer.email,
        customer_name: p.customer.name
      },
      timestamp: webhook.payload.timestamp
    };
  }
  return webhook;
}

Registrar el ciclo de vida de una suscripción con Track

Registra eventos Subscription Started y Subscription Cancelled:

track_subscriptions.js

function handler(webhook) {
  const s = webhook.payload.data;
  switch (webhook.eventType) {
    case "subscription.active":
      webhook.url = "https://api.segment.io/v1/track";
      webhook.payload = {
        userId: s.customer.customer_id,
        event: "Subscription Started",
        properties: {
          subscription_id: s.subscription_id,
          product_id: s.product_id,
          amount: (s.recurring_pre_tax_amount / 100).toFixed(2),
          frequency: s.payment_frequency_interval,
          next_billing: s.next_billing_date,
          customer_email: s.customer.email
        },
        timestamp: webhook.payload.timestamp
      };
      break;
    case "subscription.cancelled":
      webhook.url = "https://api.segment.io/v1/track";
      webhook.payload = {
        userId: s.customer.customer_id,
        event: "Subscription Cancelled",
        properties: {
          subscription_id: s.subscription_id,
          product_id: s.product_id,
          cancelled_at: s.cancelled_at,
          cancel_at_next_billing: s.cancel_at_next_billing_date,
          customer_email: s.customer.email
        },
        timestamp: webhook.payload.timestamp
      };
      break;
  }
  return webhook;
}

Identificar las propiedades del cliente

Actualiza los traits del cliente después de cada pago completado correctamente. Cada llamada Identify establece los traits con los valores que envía, por lo que estos traits describen el pago más reciente:

identify_customer.js

function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.url = "https://api.segment.io/v1/identify";
    webhook.payload = {
      userId: p.customer.customer_id,
      traits: {
        email: p.customer.email,
        name: p.customer.name,
        last_payment_amount: (p.total_amount / 100).toFixed(2),
        payment_method: p.payment_method || "unknown",
        last_payment_date: webhook.payload.timestamp
      }
    };
  }
  return webhook;
}

Consejos

Usa nombres de eventos coherentes en toda tu integración, como el formato de objeto y acción de Segment en Payment Completed.
Incluye las propiedades que necesitas para el análisis y la segmentación.
Establece timestamp a partir de timestamp del evento, para que Segment registre cuándo ocurrió el evento y no cuándo llegó.
Usa customer_id de Dodo Payments como userId, para que cada llamada de un cliente se asocie al mismo usuario de Segment.

Solución de problemas

Events Not Appearing in Segment

Comprueba que la Write Key pertenece a una fuente HTTP API y que el encabezado Authorization usa autenticación Basic.
Segment devuelve 200 para la mayoría de las solicitudes, incluidas las que no acepta, por lo que una entrega correcta en los registros de Dodo Payments no demuestra que el evento haya llegado. Comprueba el Debugger de la fuente en Segment.
Comprueba que los nombres de los eventos siguen las convenciones de nomenclatura de Segment.
Comprueba que cada llamada establece userId. Segment rechaza una llamada que no tenga ni un userId ni un anonymousId.
Comprueba los límites de frecuencia de Segment para la HTTP API. Segment recomienda mantenerse por debajo de 1.000 solicitudes por segundo por espacio de trabajo.
Si tu espacio de trabajo usa la región de la UE de Segment, envía las llamadas a https://events.eu1.segmentapis.com/v1/track y https://events.eu1.segmentapis.com/v1/identify en su lugar.

Transformation Errors

Comprueba que la carga útil coincide con el formato de la API de Segment.
Comprueba que todos los campos obligatorios están presentes. Track requiere event, y tanto Track como Identify requieren un userId o un anonymousId.
Comprueba que los nombres de los eventos sean cadenas y no objetos.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

Introducción

Comenzando

Ejemplos de código de transformación

Registrar eventos de pago con Track

Registrar el ciclo de vida de una suscripción con Track

Identificar las propiedades del cliente

Consejos

Solución de problemas

​Introducción

​Comenzando

​Ejemplos de código de transformación

​Registrar eventos de pago con Track

​Registrar el ciclo de vida de una suscripción con Track

​Identificar las propiedades del cliente

​Consejos

​Solución de problemas

Introducción

Comenzando

Ejemplos de código de transformación

Registrar eventos de pago con Track

Registrar el ciclo de vida de una suscripción con Track

Identificar las propiedades del cliente

Consejos

Solución de problemas