Changement de palier (tier/changed)

Enkore envoie un webhook à chaque fois qu'un consommateur change de palier (promotion, rétrogradation, affectation initiale, ou réévaluation périodique). Ce document décrit le payload de cet événement et ses déclencheurs.

Les headers, la signature HMAC et la politique de réessai sont communs à tous les webhooks et sont décrits dans Livraison et signature des webhooks.

---

Déclencheurs

Le webhook tier/changed est émis dans quatre situations :

Raison (reason)	Description
promotion	Le consommateur monte d'un palier (ex : passe de Silver à Gold)
demotion	Le consommateur descend d'un palier (ex : passe de Gold à Silver)
initial	Le consommateur est affecté à son premier palier
evaluation	Réévaluation périodique sans changement de direction particulier

---

Format du payload

Enkore envoie une requête POST en application/json vers l'URL configurée dans le back-office.

Exemple de payload — promotion

{
  "event": "tier/changed",
  "customerId": 42,
  "reason": "promotion",
  "pointsInPeriod": 1250,
  "from": {
    "name": "Silver",
    "slug": "silver",
    "rank": 1,
    "minPoints": 500
  },
  "to": {
    "name": "Gold",
    "slug": "gold",
    "rank": 2,
    "minPoints": 1000
  }
}

Exemple de payload — affectation initiale

Lors de la première affectation d'un consommateur à un palier, le champ from est null.

{
  "event": "tier/changed",
  "customerId": 42,
  "reason": "initial",
  "pointsInPeriod": 0,
  "from": null,
  "to": {
    "name": "Bronze",
    "slug": "bronze",
    "rank": 0,
    "minPoints": 0
  }
}

Description des champs

Champ	Type	Description
event	string	Toujours "tier/changed"
customerId	number	Identifiant externe du consommateur (correspond à l'ID dans votre plateforme e-commerce)
reason	string	Raison du changement : promotion, demotion, initial, ou evaluation
pointsInPeriod	number	Nombre de points cumulés sur la période d'évaluation
from	object | null	Palier de départ. null si c'est la première affectation
from.name	string	Nom du palier de départ
from.slug	string	Slug du palier de départ
from.rank	number	Rang du palier de départ (0 = palier le plus bas)
from.minPoints	number	Points minimum requis pour ce palier
to	object	Palier d'arrivée
to.name	string	Nom du nouveau palier
to.slug	string	Slug du nouveau palier
to.rank	number	Rang du nouveau palier
to.minPoints	number	Points minimum requis pour ce palier

---

Points d'attention côté réception

• L'envoi est asynchrone et intervient peu après la mise à jour du palier : ne présumez pas d'un ordre d'arrivée strict entre ce webhook et vos autres flux.
• Un changement de palier fait le plus souvent suite à un gain de points. Un webhook points_event/created peut donc être immédiatement suivi d'un tier/changed pour le même consommateur.
• Rendez le traitement idempotent : un même événement peut être livré plusieurs fois (voir la section déduplication de la page commune).