Passer au contenu principal
Chaque événement que Boble envoie à votre endpoint suit la même structure. Les seuls champs qui changent d’un événement à l’autre sont le type et le contenu de data.object. Tout le reste est constant.

​
L’enveloppe

{
  "id": "0d6d31a3-2b9e-4d9f-9a51-3b9c3f8e6c10",
  "type": "user_promotion.access_granted",
  "api_version": "2026-01-01",
  "created": 1717497600,
  "livemode": true,
  "data": {
    "object": { /* le payload spécifique à l'événement */ }
  }
}
​
id
string
Identifiant unique de cette livraison. Le renvoi (resend) d’un même événement logique utilise un nouvel id, pas celui d’origine.
​
type
string
Le nom de l’événement. Voir Types d’événements pour la liste complète et ce que chacun signifie.
​
api_version
string
Version du schéma du payload. Vaut actuellement toujours 2026-01-01. Si le schéma évolue un jour, la nouvelle version sera annoncée et l’ancienne continuera de fonctionner pendant une période de transition.
​
created
number
Timestamp Unix en secondes indiquant le moment où Boble a émis l’événement.
​
livemode
boolean
true en production, false dans tout environnement de test (y compris un événement de test déclenché manuellement hors production).
​
data.object
object
Le payload spécifique à l’événement. Sa forme dépend du type. La structure complète de chaque événement est dans Types d’événements.

​
Les en-têtes

Boble ajoute trois en-têtes sur chaque livraison :
En-têteValeur
Content-Typeapplication/json
User-AgentBoble-Webhook/1.0 — utile pour filtrer le trafic Boble dans vos logs.
Boble-SignatureLa signature HMAC du body. Voir Vérification de signature.
Boble-Event-IdCorrespond à l’id dans le body. Un renvoi utilise un nouvel id.

​
Le même acheteur partout

Tous les événements user_promotion.* partagent les mêmes objets imbriqués user et promotion. Conséquence : une fois que vous savez extraire l’email de l’acheteur d’un événement, le même chemin marche pour tous les événements.

​
Objet user

ChampDescription
idUUID de l’acheteur.
emailAdresse email. Peut valoir null si le compte a été supprimé.
firstnamePrénom. Peut valoir null.
lastnameNom. Peut valoir null.
usernameNom d’utilisateur sur Boble. Peut valoir null.
avatarURL complète de l’avatar. null si non défini.
preferred_languageCode IETF : en, fr, es. Peut valoir null.
created_atTimestamp ISO-8601 de la création du compte acheteur. Peut valoir null.

​
Objet promotion

ChampDescription
idUUID de la promotion.
titleTitre de la promotion.
typefree, one_time, ou subscription.
currencyCode ISO-4217 en majuscules : EUR, USD, GBP.
amountPrix dans la devise de la promotion. null pour les promotions gratuites.

​
Le même id à travers le cycle de vie

Pour un même couple acheteur/promotion, le data.object.id reste identique sur tous les événements. Le premier access_granted et un canceled ultérieur pour le même accès porteront le même data.object.id. Utilisez-le si vous voulez suivre le parcours d’un acheteur d’un événement à l’autre. L’id racine (et l’en-tête Boble-Event-Id) est unique par livraison — différent à chaque événement, et de nouveau différent à chaque renvoi.

​
Éviter la double exécution

Boble ne réessaie pas automatiquement, mais un renvoi manuel envoie une livraison flambant neuve, avec le même data.object mais un id d’enveloppe différent. Si votre handler a des effets de bord que vous ne voulez pas appliquer deux fois (envoyer un reçu, donner un rôle externe), basez votre clé d’idempotence sur une valeur dérivée de data.object — typiquement data.object.id combiné au type de l’événement. Ainsi, l’original et tous ses renvois retombent sur la même clé.