Webhook premium | Documentation Bao

Le webhook direct est le tuyau générique des rôles premium. N’importe quelle source peut le déclencher : votre site, un backend de jeu, un pont Make ou Zapier, une plateforme de vente.

Endpoint

POST /webhooks/premium/{guildId}
Content-Type: application/json
Authorization: Bearer <secret du serveur>

Le secret est propre à chaque serveur. Il se génère depuis le dashboard, s’affiche une seule fois, et se régénère à volonté. L’en-tête x-premium-secret est accepté comme alternative à Authorization.

Corps de la requête

{
  "tier": "or",
  "active": true,
  "discordId": "123456789012345678",
  "email": "client@exemple.com",
  "ref": "sub_42",
  "lifetime": false,
  "expiresAt": "2026-12-31T23:59:59Z",
  "graceDays": 7
}

Champ	Type	Rôle
`active`	booléen	`true` ouvre le droit, `false` le ferme. Défaut : `true`
`tier`	chaîne	Clé du palier. Facultatif s’il n’existe qu’un seul palier
`discordId`	chaîne	Identifiant Discord du membre
`email`	chaîne	Email de l’acheteur, pour la réclamation
`ref`	chaîne	Votre référence (identifiant d’abonnement, de commande…)
`lifetime`	booléen	Accès à vie, jamais retiré automatiquement
`expiresAt`	ISO 8601	Le droit tombe seul à cette date. Ignoré si `lifetime`
`graceDays`	entier	Force le délai de grâce au retrait. `0` = immédiat

Le modèle par état

Il n’y a aucun champ action, event ou status. Le seul discriminant est active. Vous décrivez l’état souhaité, Bao réconcilie.

Ouvrir (active: true) exige un palier, et discordId ou email.
Fermer (active: false) exige seulement de retrouver le droit : ref suffit, et c’est la voie recommandée. Vous n’avez pas à conserver une identité juste pour annuler.

Idempotence

Fournissez ref. Les rappels portant la même référence mettent à jour le même droit. Rejouer un octroi ne crée jamais de doublon : vous pouvez relancer un appel en cas de doute.

Réponses

Code	Signification
`202`	Traité. Le corps contient le résultat
`400`	Requête incomplète ou palier inconnu
`401`	Secret invalide
`404`	Fonctionnalité, source ou secret non configurés sur ce serveur
`500`	Erreur interne. L’appel peut être rejoué sans risque

Résultats possibles dans un 202 :

Résultat	Signification
`granted`	Droit ouvert, rôle attribué
`pending_claim`	Droit créé en attente : la personne doit le réclamer dans Discord
`grace_scheduled`	Retrait programmé après la période de grâce
`revoked`	Droit fermé, rôle retiré
`not_found`	Aucun droit correspondant à retirer

Exemples

Ouvrir un accès pour un membre connu :

curl -X POST https://<url-de-bao>/webhooks/premium/123456789012345678 \
  -H "Authorization: Bearer bao_prm_..." \
  -H "Content-Type: application/json" \
  -d '{"tier":"or","active":true,"discordId":"987654321098765432","ref":"sub_42"}'

Ouvrir un accès pour un acheteur qui n’a donné que son email :

curl -X POST https://<url-de-bao>/webhooks/premium/123456789012345678 \
  -H "Authorization: Bearer bao_prm_..." \
  -H "Content-Type: application/json" \
  -d '{"tier":"or","active":true,"email":"client@exemple.com","ref":"cmd_1042"}'

Fermer un accès :

curl -X POST https://<url-de-bao>/webhooks/premium/123456789012345678 \
  -H "Authorization: Bearer bao_prm_..." \
  -H "Content-Type: application/json" \
  -d '{"active":false,"ref":"sub_42"}'

Pièges à connaître

Le 404 n’est pas une erreur de code. Il signifie que la fonctionnalité est coupée, la source désactivée, ou qu’aucun secret n’a été généré. Vérifiez la configuration avant de chercher côté client.
Un membre absent du serveur n’est pas un échec. Le droit est conservé et le rôle est posé à son arrivée. N’implémentez pas de file d’attente.
Un 202 ne garantit pas que le rôle est posé. Si le rôle de Bao est sous le rôle premium, l’attribution échoue et n’apparaît que dans le journal d’audit premium. C’est la cause numéro un des rôles manquants.

Journal des livraisons

Chaque appel reçu est consigné avec son résultat et une explication lisible : secret invalide, palier inconnu, droit déjà retiré. Vous pouvez diagnostiquer seul un 401 ou un 404 depuis le dashboard, sans nous écrire.