Événements : clients, adresses et inscriptions marketing

Cette page décrit les six clés du compte client, des adresses et de l’inscription à vos listes marketing. Deux points à lire avant de coder : l’événement client part bien plus souvent qu’on ne l’imagine, et une modification d’adresse déclenche toujours une cascade vers les expéditions et les commandes, même sans rapport avec la livraison.

Objet client

Champ	Type	Nullable	Description
id	entier	non	Identifiant interne.
email	chaîne	non	Adresse e-mail actuelle.
uuid	chaîne	non	Identifiant public (cus_...), à préférer à id comme clé.
refp	chaîne	non	URL de parrainage, construite avec le domaine de votre boutique.
has_active_subscription	booléen	non	Recalculé à chaque envoi, pas au moment du fait déclencheur.
info	tableau ou nul	oui	Commentaires internes de la fiche client.

Objet adresse

Champ	Type	Nullable	Description
id	entier	non	Identifiant de l’adresse.
user_id	entier	non	Client propriétaire.
address	chaîne	non	Première ligne d’adresse.
address1	chaîne	oui	Complément d’adresse.
postcode	chaîne	non	Code postal.
city	chaîne	non	Ville.
phone	chaîne	oui	Téléphone, normalisé au format international si possible.
first_name, last_name	chaîne	non	Nom du destinataire.
region_id	entier	non	Région interne.
division, division_name	chaîne	oui	Subdivision administrative, selon le pays.
deletable	booléen	non	Calcul de droits fait au moment de l’envoi, pas un état stable : ne le stockez pas.
company_name	chaîne	oui	Raison sociale, pour une adresse professionnelle.
country	objet	non	Voir « Objet pays », toujours présent.
external_id	entier	oui	Identifiant venu d’un import historique.

Objet pays

Toujours présent dans l’objet adresse, jamais nul.

Champ	Type	Nullable	Description
id	entier	non	Identifiant interne.
name	chaîne	non	Nom du pays.
alphaCode	chaîne	non	Code ISO à deux lettres (FR).

Objet inscription marketing

Quatre champs, sans identifiant : la clé fonctionnelle est le couple adresse e-mail et boutique.

Champ	Type	Nullable	Description
email	chaîne	non	Adresse e-mail inscrite.
tenant_id	entier	non	Identifiant de votre boutique.
valid	booléen	non	Vrai si active, faux si désinscrite ou rejetée.
list_id	chaîne	oui	Liste marketing chez votre prestataire d’envoi.

created_user

Objet envoyé : client complet. Délai avant envoi : aucun. Exemple complet : dans le contrat OpenAPI (/openapi/ciklik-webhooks.yaml), webhook created_user.

Quand il part

À chaque création réelle de compte : inscription sur votre boutique, création par l’API (POST /customers), passage en caisse, et validation d’un panier PrestaShop (le client est créé à cet instant s’il n’existait pas encore).

Quand il ne part pas

Sur des créations techniques sans marchand identifié : compte créé par le webhook interne d’abonnement, ou par une action interne d’attribution de permissions.

Ce que contient changed

Toujours un tableau vide.

Effets en cascade

Aucun.

Exemple

created_user

{
    "id": 1,
    "email": "claire.martin@example.com",
    "uuid": "cus_Qx7hR3eaEowcv1DX",
    "refp": "https://boutique.example.com/formules?refp=CLAIRE2026",
    "has_active_subscription": false,
    "info": null,
    "changed": []
}

updated_user

Objet envoyé : client complet, avec les valeurs à jour. Délai avant envoi : aucun. Exemple complet : dans le contrat OpenAPI (/openapi/ciklik-webhooks.yaml), webhook updated_user (le reste de la charge utile est identique à celle de created_user).

C’est le point sensible de cette page.

Quand il part

Sur tout changement métier (e-mail, informations de compte), mais aussi sur des faits purement techniques liés à la session ou à la sécurité du compte, sans qu’aucune donnée métier n’ait changé : une connexion avec « se souvenir de moi », une simple déconnexion, l’activation ou la désactivation de la double authentification, une réinitialisation de mot de passe.

Quand il ne part pas

Sur quelques écritures silencieuses : pose du parrain juste après l’inscription, import de clients par fichier CSV, mise à jour d’un identifiant d’import historique.

Ce que contient changed

Les champs réellement modifiés, en valeur brute telle que stockée en base. Certains sont des éléments internes d’authentification ou de session, sans intérêt métier.

Attention à l’interprétation

Ne déclenchez une action métier que si un champ que vous exploitez a réellement changé : l’événement part très souvent sans aucun changement métier, sur de simples faits de session ou de sécurité du compte. N’enregistrez pas les champs que vous ne comprenez pas : certains sont des éléments d’authentification interne au client, jamais utiles côté marchand, dont la présence dans changed peut varier sans préavis.

Effets en cascade

Un changement d’adresse e-mail produit, en plus de l’updated_user, un updated_shippingbox par expédition planifiée depuis le premier jour de l’avant-dernier mois (M-2, par exemple le 1er juillet pour un envoi en septembre). Un client dont l’e-mail change et qui a 12 expéditions dans cette fenêtre déclenche 1 updated_user puis 12 updated_shippingbox, chacun avec l’e-mail à jour dans changed. Voir Événements : expéditions.

Exemple

changed de updated_user

{
    "email": "claire.martin-dupont@example.com"
}

created_address

Objet envoyé : adresse complète. Délai avant envoi : aucun. Exemple complet : dans le contrat OpenAPI (/openapi/ciklik-webhooks.yaml), webhook created_address.

Quand il part

À chaque création réelle d’adresse : ajout par le client ou par votre équipe (la création par l’API vendors n’est actuellement pas fonctionnelle).

Quand il ne part pas

Sur l’import d’adresses par fichier CSV.

Ce que contient changed

Toujours un tableau vide.

Effets en cascade

Aucun. Une adresse qui vient d’être créée n’est encore liée à aucun abonnement.

Exemple

created_address

{
    "id": 1,
    "user_id": 1,
    "address": "12 rue des Lilas",
    "address1": "Bâtiment B, 3e étage",
    "postcode": "69003",
    "city": "Lyon",
    "phone": "+33612345678",
    "first_name": "Claire",
    "last_name": "Martin",
    "region_id": 1,
    "division": null,
    "division_name": null,
    "deletable": false,
    "company_name": null,
    "country": {
        "id": 1,
        "name": "France",
        "alphaCode": "FR"
    },
    "external_id": 4821,
    "changed": []
}

updated_address

Objet envoyé : adresse complète, avec les valeurs à jour. Délai avant envoi : aucun. Exemple complet : dans le contrat OpenAPI (/openapi/ciklik-webhooks.yaml), webhook updated_address (le reste de la charge utile est identique à celle de created_address).

Quand il part

À chaque modification d’un champ de l’adresse : rue, code postal, ville, téléphone, nom du destinataire.

Quand il ne part pas

Rien de particulier à signaler ici : toute écriture réelle sur l’adresse déclenche l’événement.

Ce que contient changed

Les champs réellement modifiés par l’appelant, avec leur nouvelle valeur.

Effets en cascade

updated_address déclenche systématiquement la cascade vers les expéditions et les commandes, quel que soit le champ modifié, y compris sans rapport avec la livraison : le code ne teste pas quel champ a changé, il réagit à tout enregistrement de l’adresse. Pour chaque abonnement lié à cette adresse : un updated_shippingbox par expédition planifiée depuis le premier jour du mois M-2, puis un ou deux updated_checkoutorder par commande en cours de création. Une adresse liée à plusieurs abonnements multiplie la cascade d’autant.

updated_address -> pour chaque abonnement lié
                      -> updated_shippingbox (une par expédition depuis M-2)
                      -> updated_checkoutorder (une ou deux par commande en création)

Exemple

changed de updated_address

{
    "address": "27 avenue Jean Jaurès",
    "address1": "",
    "postcode": "69007"
}

created_optin

Objet envoyé : inscription marketing complète. Délai avant envoi : 10 secondes. Exemple complet : dans le contrat OpenAPI (/openapi/ciklik-webhooks.yaml), webhook created_optin.

Quand il part

Uniquement à la toute première inscription d’un couple e-mail et boutique : à l’inscription, ou à la création, l’annulation ou la réactivation d’un abonnement quand ce couple n’a encore aucune inscription.

Quand il ne part pas

Toute réinscription ultérieure du même couple n’est pas un nouveau created_optin : c’est un updated_optin, puisque l’inscription existe déjà.

Ce que contient changed

Toujours un tableau vide.

Effets en cascade

Aucun.

Exemple

created_optin

{
    "email": "claire.martin@example.com",
    "tenant_id": 1,
    "valid": true,
    "list_id": "9f2c4e7a1b",
    "changed": []
}

updated_optin

Objet envoyé : inscription marketing complète, avec les valeurs à jour. Délai avant envoi : aucun. Exemple complet : dans le contrat OpenAPI (/openapi/ciklik-webhooks.yaml), webhook updated_optin (le reste de la charge utile est identique à celle de created_optin).

Quand il part

Sur quatre faits : une réinscription d’un couple déjà connu, une désinscription volontaire (valid passe à false), un rejet définitif par votre fournisseur d’envoi d’e-mail (« hard bounce » constaté à une tentative d’inscription), et une désinscription en masse faite par votre équipe. Cette dernière produit un updated_optin par inscription du lot, pas un seul événement global.

Quand il ne part pas

Rien au-delà de ces quatre cas.

Ce que contient changed

Le plus souvent valid, seul ou avec list_id en cas de changement de liste.

Effets en cascade

Aucun.

Exemple

changed de updated_optin

{
    "valid": false
}

Ce qui n’existe pas

Il n’existe ni deleted_address, ni deleted_user, ni deleted_optin : ces trois clés ne figurent pas dans la liste des événements disponibles. La suppression d’une adresse par l’API ne déclenche aucun envoi. Ne comptez pas sur un webhook pour détecter la suppression d’un client, d’une adresse ou d’une inscription marketing : interrogez l’API si vous avez besoin de le savoir.