Présentation des webhooks

Lisoloo livre les mises à jour de statut de façon asynchrone à une URL que vous configurez sur votre clé API. Chaque événement est un seul POST HTTP avec un corps JSON et les identifiants HTTP Basic optionnels que vous avez définis.

Pourquoi les webhooks

Pour tout envoi de plus que quelques destinataires, interroger GET /status/{message_id} est le mauvais outil — cela brûle votre limite de débit 120 lectures/minute et ajoute de la latence. Les webhooks poussent l’état final directement vers votre serveur, en temps réel, gratuitement (aucun coût supplémentaire de limite de débit chez vous).

                 ┌──────────────┐  webhook POST   ┌────────────────┐
   POST /send ─▶ │  Lisoloo API │ ──────────────▶ │ Votre endpoint │
                 └──────────────┘  à chaque event └────────────────┘
                       │
                       └─ transitions de statut internes :
                          pending → processing → sent → delivered

Sémantique de livraison

• Méthode HTTP : POST.
• Content-Type : application/json.
• Corps : un seul objet événement (voir Types d’événements).
• Authentification : HTTP Basic avec les identifiants configurés sur votre clé API, si définis. Pas de signature HMAC aujourd’hui.
• Relances : jusqu’à 4 tentatives sur les réponses 5xx ou les échecs de connexion, avec backoff exponentiel 30s → 2m → 10m → 1h. Après 4 échecs l’événement est abandonné.
• Ordre : pas garanti. Un événement sms.delivered pour un destinataire peut arriver avant l’événement sms.sent pour un autre du même lot. Utilisez recipient_phone pour corréler ; basez- vous sur l’état faisant autorité dans GET /status si l’ordre compte.
• Idempotence : chaque événement a un event_id (UUID v4). Votre endpoint doit être idempotent — un replay avec le même event_id doit être un no-op.

Configurer un webhook

La configuration de webhook vit sur la clé API, pas sur le compte marchand. Vous la configurez dans le portail développeur :

1. Ouvrez Bloonio → Lisoloo → Developer → Clés API.
2. Déroulez vers Configuration webhook.
3. Définissez webhook_url à un endpoint HTTPS sur votre serveur.
4. (Optionnel mais recommandé) définissez webhook_basic_auth_username et webhook_basic_auth_password. La passerelle utilisera ceux-ci pour l’auth HTTP Basic sur chaque POST.
5. Enregistrez.

La visite guidée complète — y compris le champ mot de passe write-only et l’indicateur « Basic auth configured » — est à Webhooks → Configuration.

Ce que vous recevrez

Chaque événement a la même enveloppe extérieure :

{
  "event_id":    "f8a3b7c1-2e4d-4a9b-9d8f-7c6e5b4a3d2c",
  "event_type":  "sms.delivered",
  "timestamp":   "2026-05-27T10:15:08Z",
  "message_id":  "507f1f77bcf86cd799439011",
  "data": {
    ...charge utile spécifique à l'événement...
  }
}

Les valeurs event_type et les formes data par événement sont documentées à Types d’événements webhook.

Ce que vous devez renvoyer

Un statut 2xx (200, 201 ou 204) acquitte l’événement. Le corps est ignoré. Tout 4xx est traité comme un échec permanent (l’événement ne sera pas retenté — typiquement utilisé pour refuser les événements mal routés). Tout 5xx ou erreur de connexion déclenche la séquence de relance.

HTTP/1.1 204 No Content

Visez à répondre en moins de 5 secondes. Les acks au-delà de 5 secondes sont traités comme un timeout et déclenchent une relance. Si votre traitement est lent, acceptez d’abord et traitez en async — poussez l’événement dans une file et renvoyez 204 immédiatement.

Vérification de signature — pas encore

Il n’y a actuellement pas d’en-tête de signature HMAC sur les webhooks sortants. Auth HTTP Basic + une liste blanche sur votre pare-feu est la posture recommandée. Les webhooks signés sont sur la feuille de route ; nous l’annoncerons sur le changelog quand cela arrivera.

Tester les webhooks en local

webhook.site et smee.io exposent tous deux une URL publique qui forwarde vers votre poste. Utile pour l’intégration précoce ; pour le routage de production utilisez votre propre domaine avec TLS.

Pour les tests unitaires, le sandbox webhook_url accepte n’importe quelle URL HTTPS — déclenchez un sandbox POST /send contre une URL webhook.site et voyez les événements arriver en quelques secondes.

Voir aussi

Configuration Le formulaire du tableau de bord, l'auth Basic, et la rotation.

Types d'événements Charges utiles par événement et ce qu'elles signifient.

Cycle de vie d'un message La machine d'états qui déclenche les événements.