Segment

Introduction

L’intégration Segment envoie les événements Dodo Payments à l’HTTP Tracking API de Segment sous forme d’appels Track et Identify. Segment transmet ensuite les données de paiement, d’abonnement et de client aux outils d’analytics, de marketing et de data warehouse connectés à votre espace de travail, parmi un catalogue de plus de 300 destinations.

Cette intégration nécessite la Write Key d’une source HTTP API dans votre espace de travail Segment. Vous devez également avoir accès à Developer → Webhooks dans le tableau de bord Dodo Payments.

Prise en main

Open the Webhook Section

Dans le tableau de bord Dodo Payments, accédez à Developer → Webhooks et cliquez sur Add endpoint.

Boîte de dialogue Add endpoint avec Segment sélectionné dans la liste déroulante Integration et les étapes How to connect Segment

Select Segment

Dans Integration, sélectionnez Segment. Le tableau de bord renseigne automatiquement l’Endpoint URL et le code de transformation pour Segment.

Enter Write Key

Dans Segment, accédez à Connections → Sources, puis ouvrez ou créez une source HTTP API. Copiez la Write Key dans les paramètres de la source et collez-la dans API key.

Select Events

Dans Subscribed events, sélectionnez uniquement les événements gérés par votre transformation. Les exemples de cette page utilisent payment.succeeded, subscription.active et subscription.cancelled.

Configure Transformation

Sous Transformation code, modifiez le handler pour formater les événements destinés à l’API Track ou Identify de Segment. Commencez par les exemples.

Test & Create

Sous Test this code, sélectionnez un type d’événement et cliquez sur Simulate pour prévisualiser l’appel à Segment. Cliquez ensuite sur Create endpoint.

Switch to Basic Authentication

Dodo Payments envoie la valeur API key sous forme de bearer token, mais l’HTTP API de Segment accepte une Write Key via l’authentification Basic ou un champ writeKey dans le body. Juste après avoir créé l’endpoint, ouvrez son onglet Advanced. Sous Custom headers, saisissez une nouvelle valeur dans la ligne Authorization masquée : Basic, un espace, puis l’encodage Base64 de votre Write Key suivi de deux-points. Cliquez ensuite sur Save. Par exemple, echo -n 'YOUR_WRITE_KEY:' | base64 affiche la valeur encodée.

Done

Les événements abonnés sont désormais transmis à Segment, qui les relaie vers vos destinations connectées.

Exemples de code de transformation

Chaque handler définit webhook.url sur un endpoint d’API Segment et remplace webhook.payload par l’appel. Les montants Dodo Payments sont exprimés dans la plus petite unité monétaire ; les exemples les divisent donc par 100. Pour les devises sans décimales, comme JPY et KRW, utilisez le montant tel quel.

Suivre les événements de paiement avec Track

Enregistrez un événement Payment Completed lorsqu’un paiement réussit :

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;
}

Suivre le cycle de vie d’un abonnement

Enregistrez les événements Subscription Started et 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;
}

Identifier les propriétés du client

Mettez à jour les traits du client après chaque paiement réussi. Chaque appel Identify définit les traits sur les valeurs qu’il envoie ; ces traits décrivent donc le dernier paiement :

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;
}

Conseils

Utilisez des noms d’événements cohérents dans toute votre intégration, comme le format objet et action de Segment dans Payment Completed.
Incluez les propriétés dont vous avez besoin pour l’analytics et la segmentation.
Définissez timestamp à partir de timestamp de l’événement, afin que Segment enregistre le moment où l’événement s’est produit plutôt que celui où il est arrivé.
Utilisez customer_id de Dodo Payments comme userId, afin que chaque appel pour un client soit associé au même utilisateur Segment.

Résolution des problèmes

Events Not Appearing in Segment

Vérifiez que la Write Key appartient à une source HTTP API et que l’en-tête Authorization utilise l’authentification Basic.
Segment renvoie 200 pour la plupart des requêtes, y compris celles qu’il n’accepte pas ; une livraison réussie dans les logs Dodo Payments ne prouve donc pas que l’événement est arrivé. Consultez le Debugger de la source dans Segment.
Vérifiez que les noms d’événements respectent les conventions de nommage de Segment.
Vérifiez que chaque appel définit userId. Segment rejette un appel qui ne contient ni userId ni anonymousId.
Vérifiez les limites de débit de Segment pour l’HTTP API. Segment recommande de rester sous 1 000 requêtes par seconde et par espace de travail.
Si votre espace de travail utilise la région UE de Segment, envoyez les appels à https://events.eu1.segmentapis.com/v1/track et https://events.eu1.segmentapis.com/v1/identify à la place.

Transformation Errors

Vérifiez que le payload respecte le format d’API de Segment.
Vérifiez que tous les champs obligatoires sont présents. Track nécessite event, et Track comme Identify nécessitent userId ou anonymousId.
Vérifiez que les noms d’événements sont des chaînes de caractères et non des objets.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

Introduction

Prise en main

Exemples de code de transformation

Suivre les événements de paiement avec Track

Suivre le cycle de vie d’un abonnement

Identifier les propriétés du client

Conseils

Résolution des problèmes

​Introduction

​Prise en main

​Exemples de code de transformation

​Suivre les événements de paiement avec Track

​Suivre le cycle de vie d’un abonnement

​Identifier les propriétés du client

​Conseils

​Résolution des problèmes

Introduction

Prise en main

Exemples de code de transformation

Suivre les événements de paiement avec Track

Suivre le cycle de vie d’un abonnement

Identifier les propriétés du client

Conseils

Résolution des problèmes