API Klaviyo : envoyer des events depuis votre stack

À notre avis, la majorité des guides Klaviyo partent du principe que votre stack technique est Shopify ou WooCommerce. Vous installez le plugin, vous activez la connexion native, tout remonte automatiquement. Mais si vous avez une application SaaS, une plateforme custom, un système de fidélité maison, ou même un checkout développé en interne, cette logique ne s'applique plus.

Pour ces cas, Klaviyo expose une API qui permet d'envoyer des events depuis votre propre backend, de profiler vos utilisateurs avec des propriétés custom, et de déclencher des flows depuis votre propre backend. C'est précisément ce que cet article couvre : les fondamentaux techniques pour intégrer Klaviyo dans une stack non standard.

TL;DR

• L'API Klaviyo permet d'envoyer des events avec un endpoint central : POST /api/events/. La payload suit un format JSON strict avec metric, profile et properties.
• Deux mécanismes d'envoi coexistent : l'API server-side (backend, clé privée) et Klaviyo.js (frontend, clé publique). Chacun a son périmètre d'usage.
• Klaviyo ne "pousse" pas des webhooks entrants : il reçoit des events via API. En revanche, Klaviyo peut envoyer des webhooks sortants vers vos endpoints via une action dédiée dans les Flows.
• Les limites de débit varient selon l'endpoint et sont indiquées dans chaque page de référence. Un dépassement retourne un 429 Too Many Requests : votre intégration doit respecter Retry-After et appliquer un backoff.
• À notre avis, les erreurs les plus fréquentes sont liées à l'authentification (confusion clé publique / privée), au format du profil (champs manquants) et aux valeurs metric.name incohérentes entre les events.

API Klaviyo : les fondamentaux

Authentification : clé privée vs clé publique

Klaviyo distingue deux types de clés, et la confusion entre les deux est la première source d'erreurs sur les intégrations custom.

La clé privée (Private API Key) commence par pk_. D'après le guide d'authentification, elle permet de lire et d'écrire des données dans votre compte, dans la limite des scopes de la clé (par exemple events:write pour créer des events). Cette clé ne doit jamais être exposée côté client. Elle s'utilise dans le header HTTP de chaque requête :

Authorization: Klaviyo-API-Key pk_xxxxxxxxxxxxxxxxxxxx

La clé publique (Public API Key ou Site ID) est à 6 caractères alphanumériques. Elle est conçue pour les appels depuis le navigateur via Klaviyo.js. Selon le même guide, elle ne permet pas d'accéder aux données sécurisées de votre compte et peut être partagée.

Pour retrouver vos clés : Settings, puis API keys (rôle Owner, Admin ou Manager requis).

Endpoints principaux

L'API est accessible à la base URL https://a.klaviyo.com/api/. Les endpoints les plus utiles pour une intégration custom :

Chaque requête doit inclure le header de révision de l'API :

revision: YYYY-MM-DD

Ce header sélectionne une révision du schéma. Utilisez une révision encore supportée et testée par votre intégration, puis planifiez sa mise à jour à partir de la documentation officielle Klaviyo.

Rate limits

Klaviyo publie des limites propres à chaque endpoint, avec une fenêtre burst d'1 seconde et une fenêtre steady d'1 minute (guide des limites de débit). Au moment de la relecture, la page Create Event indique 350/s en burst et 3 500/min en steady : consultez-la à l'implémentation. Klaviyo retourne un 429 Too Many Requests en cas de dépassement, avec un header Retry-After indiquant le délai d'attente.

Pour les intégrations à fort volume (ex : event batch lors d'un import ou d'une migration), l'endpoint Bulk Create Events (/api/event-bulk-create-jobs) accepte jusqu'à 1 000 events et 5 Mo par requête (burst 10/s, steady 150/min au moment de la relecture). Pour rejouer des events historiques, Klaviyo propose un champ booléen backfill: true : l'event est enregistré et visible dans les métriques et la segmentation, mais ne déclenche pas de flow.

Envoyer un event custom : payload et exemples de code

Structure de la payload

Le corps d'un event est un objet JSON data avec type et attributes, comme dans les exemples de la vue d'ensemble de l'API Events. Voici une structure minimale :

{
  "data": {
    "type": "event",
    "attributes": {
      "metric": {
        "data": {
          "type": "metric",
          "attributes": {
            "name": "Completed Onboarding Step"
          }
        }
      },
      "profile": {
        "data": {
          "type": "profile",
          "attributes": {
            "email": "user@votre-domaine.com"
          }
        }
      },
      "properties": {
        "step_name": "profil complété",
        "plan": "pro",
        "nb_jours_depuis_inscription": 3
      },
      "time": "2026-06-04T10:00:00+00:00",
      "value": 0
    }
  }
}

Champs importants :

• metric.name : le nom de l'event tel qu'il apparaîtra dans Klaviyo. C'est ce nom qui sert de déclencheur dans les flows. Si le nom ne correspond à aucune métrique existante, Klaviyo en crée une nouvelle. Utilisez des noms cohérents et stables.
• profile.email : l'identifiant principal. Au moins un identifiant de profil est requis (id, email ou phone_number, d'après la référence Create Event).
• properties : objet libre, jusqu'à 400 propriétés par event. Klaviyo cite l'usage de ces propriétés pour personnaliser les flows, segmenter et produire des rapports.
• time : timestamp ISO 8601. Si omis, Klaviyo utilise l'heure de création de l'event.
• value : valeur monétaire optionnelle associée à l'event (utile pour les events de type "achat" ou "upgrade").

Exemple Python

import requests
import json

KLAVIYO_API_KEY = "pk_votre_cle_privee"
BASE_URL = "https://a.klaviyo.com/api"

headers = {
    "Authorization": f"Klaviyo-API-Key {KLAVIYO_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "revision": "2026-10-15"
}

payload = {
    "data": {
        "type": "event",
        "attributes": {
            "metric": {
                "data": {
                    "type": "metric",
                    "attributes": {
                        "name": "Completed Onboarding Step"
                    }
                }
            },
            "profile": {
                "data": {
                    "type": "profile",
                    "attributes": {
                        "email": "user@votre-domaine.com",
                        "first_name": "Alice",
                        "properties": {
                            "plan": "pro"
                        }
                    }
                }
            },
            "properties": {
                "step_name": "profil complété",
                "nb_jours_depuis_inscription": 3
            }
        }
    }
}

response = requests.post(
    f"{BASE_URL}/events/",
    headers=headers,
    data=json.dumps(payload)
)

if response.status_code == 202:
    print("Event accepté pour traitement")
else:
    print(f"Erreur {response.status_code} : {response.text}")

Une réponse 202 Accepted indique que l'event a été validé et soumis au traitement, sans garantir que le traitement est terminé.

Exemple JavaScript (Node.js)

const axios = require('axios');

const KLAVIYO_API_KEY = 'pk_votre_cle_privee';

const payload = {
  data: {
    type: 'event',
    attributes: {
      metric: {
        data: {
          type: 'metric',
          attributes: { name: 'Completed Onboarding Step' }
        }
      },
      profile: {
        data: {
          type: 'profile',
          attributes: { email: 'user@votre-domaine.com' }
        }
      },
      properties: {
        step_name: 'profil complété',
        plan: 'pro'
      }
    }
  }
};

axios.post('https://a.klaviyo.com/api/events/', payload, {
  headers: {
    'Authorization': `Klaviyo-API-Key ${KLAVIYO_API_KEY}`,
    'Content-Type': 'application/json',
    'revision': '2026-10-15'
  }
})
.then(res => console.log('Event accepté, status:', res.status))
.catch(err => console.error('Erreur:', err.response?.data));

Exemple cURL

curl -X POST https://a.klaviyo.com/api/events/ \
  -H "Authorization: Klaviyo-API-Key pk_votre_cle_privee" \
  -H "Content-Type: application/json" \
  -H "revision: 2026-10-15" \
  -d '{
    "data": {
      "type": "event",
      "attributes": {
        "metric": {
          "data": {
            "type": "metric",
            "attributes": { "name": "Completed Onboarding Step" }
          }
        },
        "profile": {
          "data": {
            "type": "profile",
            "attributes": { "email": "user@votre-domaine.com" }
          }
        },
        "properties": { "step_name": "profil complété" }
      }
    }
  }'

Klaviyo.js vs API server-side : quand utiliser quoi

Les deux mécanismes ne s'opposent pas : ils se complètent. Comprendre leurs périmètres respectifs évite les doublons d'events et les erreurs d'authentification.

Klaviyo.js (frontend)

Klaviyo.js est un snippet JavaScript chargé dans le navigateur. Il utilise votre clé publique (Site ID) et expose deux méthodes principales :

• klaviyo.identify({ email: '...', first_name: '...' }) : associe des propriétés à un profil côté client. Utile pour identifier un visiteur authentifié sans passer par votre backend.
• klaviyo.track('Nom de l\'event', { propriété: 'valeur' }) : envoie un event depuis le navigateur. Enregistre un event pour un utilisateur identifié (voir le guide de l'API JavaScript).

Quand l'utiliser : pour les events qui se produisent dans le navigateur. Exemple : "Viewed Product", "Started Checkout", "Clicked CTA".

Limitations : pas d'accès aux données sécurisées, et, à notre avis, dépendance au JavaScript côté client (ad-blockers, consentement).

API server-side (backend)

L'API avec clé privée est la solution pour tout ce qui se passe côté serveur : actions post-paiement, events liés à des changements d'état dans votre base de données, intégrations avec des systèmes tiers (ERP, CRM, plateforme de fidélité).

Quand l'utiliser :
- Events déclenchés par des actions backend : confirmation de commande, upgrade de plan, activation d'une feature.
- Données sensibles à ne pas exposer au navigateur (valeur d'achat, segment interne).
- Ingestion batch ou migration de données historiques.
- Environnements sans navigateur : scripts d'import, jobs CRON.

Règle simple, à notre avis : si l'event nécessite votre clé privée ou des données que vous ne voulez pas exposer au client, c'est du server-side. Sinon, Klaviyo.js peut suffire.

Webhooks sortants depuis Klaviyo (Flow Webhook action)

À notre avis, la confusion est fréquente sur ce que "webhook Klaviyo" signifie selon le sens de l'échange.

Klaviyo reçoit des events : via l'API /api/events/. C'est ce qu'on vient de décrire. Klaviyo est ici le récepteur.

Klaviyo envoie des données vers votre système : c'est possible via l'action "Webhook" disponible dans les Flows (article d'aide). Klaviyo est alors l'émetteur : il envoie une requête HTTP POST vers votre endpoint à chaque fois qu'un profil atteint ce noeud du flow.

Configurer un webhook sortant dans un Flow

1. Dans la barre latérale du flow builder, glissez l'action "Webhook" dans votre Flow (guide développeur).
2. Renseignez l'URL de votre endpoint (HTTPS obligatoire, sans certificat auto-signé ni redirection).
3. Définissez les headers si nécessaire (ex : un token d'authentification pour votre API).
4. Rédigez le corps du message en JSON (seul format pris en charge) ; un panneau permet de copier les variables du profil ou de l'event déclencheur. Les webhooks de flow n'exécutent que des requêtes POST, et la double authentification est requise.

La payload que Klaviyo envoie est du JSON que vous composez dans l'interface. Cela vous permet de notifier votre backend lorsqu'un utilisateur entre dans un segment ou atteint l'action dans un flow.

Exemples d'usage :
- Notifier votre CRM quand un lead télécharge un lead magnet et entre dans la séquence de nurturing.
- Déclencher un ticket support automatique si un client entre dans un flow "churned".
- Envoyer les données d'un client à un outil de courrier postal après un Placed Order (exemple cité par Klaviyo).

Cas d'usage concrets

SaaS : onboarding progressif

Un SaaS avec un onboarding en 5 étapes peut envoyer un event Completed Onboarding Step à chaque étape complétée, avec une propriété step_number et step_name. Klaviyo déclenche un flow différent selon le step atteint : félicitations, nudge si l'étape suivante n'est pas complétée après 48h, offre de démonstration si l'utilisateur bloque à l'étape 3.

La valeur de cette approche : Klaviyo gère la logique de communication, votre backend n'a qu'à envoyer l'event. Pas de logique d'emailing dans votre code.

DTC : events custom hors Shopify

Une marque DTC avec une plateforme de commande custom peut envoyer ses propres events, par exemple : Subscription Activated, Product Personalized, Gift Message Added. Une fois envoyés, ces events peuvent servir à segmenter et à déclencher des flows, comme n'importe quel event reçu par l'API.

Pour les custom properties sur les profils, voir notre article sur les propriétés custom Klaviyo qui couvre la gestion des champs profil enrichis.

Programme de fidélité

Un système de points maison envoie un event Points Earned avec points_added et total_points à chaque achat. Klaviyo peut déclencher des emails de célébration à chaque palier (500 points, 1 000 points), segmenter les VIP, et envoyer des rappels d'expiration de points.

Le webhook sortant de Klaviyo peut en retour notifier votre système de fidélité depuis un flow déclenché par un event (par exemple Placed Order). Klaviyo précise qu'on ne peut pas déclencher un flow à partir des ouvertures d'email, et ne prend pas en charge l'événement Received Email comme déclencheur de flow.

Erreurs fréquentes et debugging

401 Unauthorized

Le guide des codes décrit le 401 comme une requête sans information d'authentification ; le guide d'authentification indique de son côté qu'un 400 signale une clé API invalide ou absente. Une cause possible, à notre avis : la clé publique (Site ID) utilisée à la place de la clé privée. Vérifiez que votre header Authorization commence bien par Klaviyo-API-Key pk_....

400 Bad Request

Le guide des codes indique un paramètre requis manquant ou invalide. Causes possibles :
- Un header revision qui n'est pas une révision valide (la politique de versions exige une révision valide).
- À notre avis, un champ mal structuré dans la payload JSON (ex : metric directement à la racine au lieu d'être dans attributes).
- Aucun identifiant de profil valide : un email de moins de 100 caractères, ou un téléphone au format E.164 (une requête avec seulement un téléphone invalide est rejetée).

Lisez attentivement le corps de la réponse d'erreur : Klaviyo retourne un tableau errors dont les champs title et detail décrivent la cause de l'échec.

202 reçu mais l'event n'apparaît pas dans Klaviyo

Le 202 signifie que l'event est en file de traitement, pas qu'il est déjà visible. D'après la vue d'ensemble de l'API Events, les events sont créés de façon asynchrone et l'affichage peut prendre jusqu'à quelques minutes. Si l'event n'apparaît toujours pas :
- Vérifiez dans la liste des métriques de Klaviyo que le nom de la métrique correspond exactement.
- Contrôlez que l'email du profil n'est pas en @example.com ou @test.com : ces events reçoivent un 202 puis sont supprimés en silence.
- Vérifiez que le unique_id n'est pas déjà utilisé pour ce profil et cette métrique (Klaviyo dédoublonne sur profil, métrique et unique_id) et que l'identifiant de profil est correct.
- Vérifiez les logs de votre endpoint : assurez-vous que la requête a bien été envoyée.

Events dupliqués

Si vous envoyez un event depuis le frontend (Klaviyo.js) et depuis votre backend pour la même action, à notre avis Klaviyo créera deux events distincts, sauf s'ils partagent profil, métrique et unique_id. Définissez clairement quel mécanisme est responsable de quel event et documentez-le. À notre avis, les doublons faussent les métriques et peuvent déclencher des flows en double.

Metric names incohérents

À notre avis, Order Completed, order_completed et OrderCompleted risquent de devenir trois métriques différentes (Klaviyo crée une métrique quand le nom n'en correspond à aucune). Standardisez vos noms d'events dès le départ et documentez-les dans un registre partagé avec votre équipe technique. À notre avis, un changement de nom d'event peut casser les flows et segments qui en dépendent.

Pour aller plus loin

• Setup initial Klaviyo : si vous démarrez votre intégration, l'article sur le setup Klaviyo couvre la configuration de base avant de passer à l'API.
• Custom properties : pour comprendre comment structurer les propriétés profil et événement, consultez notre guide sur les custom properties Klaviyo.
• Flows vs Campaigns : une fois vos events en place, cet article sur flows et campagnes vous aide à décider quelles automations construire.
• Documentation officielle : la référence Create Event et la vue d'ensemble de l'API Events détaillent les champs et les cas particuliers.

Si votre intégration est complexe (migration de données historiques, système multi-marques, architecture microservices), notre équipe peut auditer votre setup et vous accompagner. Contactez l'agence Deliver pour en discuter.