Configuration webhook

Le routage des webhooks vit sur votre clé API. Le portail développeur expose trois champs :

Champ	Requis ?	Persisté ?
webhook_url	Oui (pour activer les webhooks)	En clair, retourné par GET sur la clé.
webhook_basic_auth_username	Non	En clair, retourné par GET.
webhook_basic_auth_password	Non	Write-only. Chiffré au repos ; jamais ré-affiché.

Définir l’URL

L’URL doit être https:// — http:// est rejeté. Aucune autre validation à la soumission (la passerelle ne ping pas votre endpoint en amont) ; le premier événement webhook qui échoue sera retenté selon la présentation puis abandonné.

webhook_url: https://merchant.example.com/lisoloo/webhook

Conventions de chemin recommandées :

• Utilisez un chemin qui identifie la source (/lisoloo/) pour que les gestionnaires de webhooks multi-tenants puissent router.
• Incluez un sous-domaine par environnement (api.staging.example.com vs api.example.com) pour que le trafic de test ne puisse pas accidentellement toucher les consommateurs de production.

Définir Basic auth

La passerelle envoie Authorization: Basic <base64(username:password)> à chaque POST webhook quand username et password sont tous deux configurés. Votre endpoint doit vérifier que cela correspond à la valeur définie dans le portail.

webhook_basic_auth_username: lisoloo_webhook_user
webhook_basic_auth_password: ••••••••••••••••••••  (write-only)

Le champ mot de passe est une entrée <p-password> dans le portail — la valeur que vous tapez est envoyée une fois et stockée chiffrée ; la prochaine fois que vous voyez le formulaire, le mot de passe n’est pas pré-rempli. Modifier le username sans re-saisir le mot de passe laisse le mot de passe existant en place.

Pour faire tourner le mot de passe : re-saisissez username et mot de passe et enregistrez. Les anciens identifiants sont invalidés immédiatement.

Pour effacer Basic auth entièrement : cliquez sur Effacer les identifiants Basic auth. La passerelle envoie alors les webhooks sans en-tête Authorization.

Toujours activer Basic auth en production

L’endpoint webhook accepte les POSTs non-authentifiés si vous ne configurez pas d’identifiants — quiconque devine l’URL peut spoofer des événements. Au minimum, définissez une paire username/password et vérifiez-la à chaque requête entrante.

Vérifier les identifiants chez vous

Vérification HTTP Basic standard — décoder l’en-tête Authorization: Basic, splitter sur :, comparer aux valeurs attendues avec une comparaison à temps constant.

import base64
import hmac
from fastapi import FastAPI, Header, HTTPException, Request

app = FastAPI()

EXPECTED_USER = os.environ["LISOLOO_WEBHOOK_USER"]
EXPECTED_PASS = os.environ["LISOLOO_WEBHOOK_PASS"]

@app.post("/lisoloo/webhook")
async def webhook(req: Request, authorization: str = Header(None)):
    if not authorization or not authorization.startswith("Basic "):
        raise HTTPException(401)
    raw = base64.b64decode(authorization.split(" ", 1)[1]).decode()
    user, _, password = raw.partition(":")
    if not hmac.compare_digest(user, EXPECTED_USER) or \
       not hmac.compare_digest(password, EXPECTED_PASS):
        raise HTTPException(401)
    # … gérer l'événement …
    return {"ok": True}

import express from "express";

const app = express();
app.use(express.json());

const EXPECTED_USER = process.env.LISOLOO_WEBHOOK_USER;
const EXPECTED_PASS = process.env.LISOLOO_WEBHOOK_PASS;

app.post("/lisoloo/webhook", (req, res) => {
  const auth = req.headers.authorization ?? "";
  if (!auth.startsWith("Basic ")) return res.sendStatus(401);
  const [user, pass] = Buffer.from(auth.slice(6), "base64")
    .toString()
    .split(":");
  if (user !== EXPECTED_USER || pass !== EXPECTED_PASS) {
    return res.sendStatus(401);
  }
  // … gérer l'événement …
  res.sendStatus(204);
});

Le drapeau webhook_basic_auth_configured

Quand vous GET la ligne de clé API depuis le portail développeur, la réponse inclut webhook_basic_auth_configured: true | false. C’est le seul signal que les identifiants sont définis ; le vrai mot de passe n’est jamais retourné. L’UI du portail utilise ce drapeau pour afficher le badge Basic auth configured sur la carte de la clé.

Liste blanche (pare-feu) — optionnel mais recommandé

Si votre pare-feu en périphérie utilise une liste blanche d’IPs sortantes, ajoutez les plages d’IP de sortie Lisoloo. Contactez votre gestionnaire de compte Bloonio pour la liste actuelle — elle est publiée hors des docs afin de pouvoir changer sans reconstruire le site.

Voir aussi

• Présentation des webhooks — sémantique de livraison
• Types d’événements — charges utiles par événement
• Clés API — le flux de gestion parent