Introduction aux Webhooks

Les webhooks sont des notifications automatiques envoyées par Bcommercy vers vos propres serveurs ou applications tierces lorsqu'un événement spécifique se produit sur votre boutique. Contrairement aux appels API classiques où vous devez interroger régulièrement le système, les webhooks vous poussent l'information en temps réel.

⚠️ Fonctionnalité à venir : Les webhooks ne sont pas encore disponibles sur Bcommercy. Cette documentation est publiée en avant-première pour vous permettre de préparer vos intégrations. Nous vous informerons dès que cette fonctionnalité sera activée.

Cette fonctionnalité avancée sera idéale si vous souhaitez :

Synchroniser vos commandes avec un ERP ou un logiciel de gestion
Déclencher des automatisations personnalisées (envoi SMS, mise à jour de stock externe)
Connecter Bcommercy à des outils comme Zapier, Make (ex-Integromat) ou n8n
Recevoir des alertes instantanées sur des événements critiques

Comment fonctionneront les Webhooks ?

Lorsqu'un événement se produira (nouvelle commande, paiement reçu, produit mis à jour...), Bcommercy enverra une requête HTTP POST vers l'URL que vous aurez configurée. Cette requête contiendra toutes les données pertinentes au format JSON.

Le flux en 4 étapes

Événement déclencheur : Un client passe une commande sur votre boutique
Notification envoyée : Bcommercy envoie instantanément les données à votre URL
Traitement : Votre serveur reçoit et traite les informations
Confirmation : Votre serveur répond avec un code HTTP 200 pour confirmer la réception

Événements prévus

Voici les principaux événements que vous pourrez surveiller via webhooks :

Commandes

order.created – Nouvelle commande passée
order.paid – Paiement confirmé (Wave, Paydunya)
order.shipped – Commande expédiée
order.delivered – Commande livrée
order.cancelled – Commande annulée

Produits

product.created – Nouveau produit ajouté
product.updated – Produit modifié
product.deleted – Produit supprimé
product.out_of_stock – Stock épuisé

Clients

customer.created – Nouveau client inscrit
customer.updated – Informations client mises à jour

Configuration d'un Webhook (à venir)

Étape 1 : Accéder aux paramètres

Connectez-vous à votre Dashboard vendeur
Rendez-vous dans Paramètres → Intégrations → Webhooks

Étape 2 : Créer un nouveau webhook

Cliquez sur « Ajouter un webhook »
Renseignez l'URL de destination (ex : https://votre-serveur.com/webhook/bcommercy)
Sélectionnez les événements à surveiller
Optionnel : ajoutez un secret de vérification pour sécuriser les échanges
Cliquez sur Enregistrer

Étape 3 : Tester votre webhook

Utilisez le bouton « Envoyer un test » pour vérifier que votre serveur reçoit bien les données
Consultez les logs de livraison pour voir l'historique des envois et les éventuelles erreurs

Structure des données envoyées

Chaque notification webhook contiendra un payload JSON structuré. Voici un exemple pour l'événement order.created :

{
  "event": "order.created",
  "timestamp": "2025-01-13T14:30:00Z",
  "shop_id": "shop_abc123",
  "data": {
    "order_id": "ord_xyz789",
    "total": 25000,
    "currency": "XOF",
    "status": "pending",
    "customer": {
      "name": "Aminata Koné",
      "phone": "+225 07 XX XX XX",
      "email": "aminata@example.com"
    },
    "items": [
      {
        "product_id": "prod_456",
        "name": "T-shirt Wax Premium",
        "quantity": 2,
        "price": 12500
      }
    ]
  }
}

Sécuriser vos Webhooks

La sécurité est essentielle pour éviter que des acteurs malveillants n'envoient de fausses notifications à votre serveur.

Vérification par signature

Lors de la création du webhook, définissez un secret de vérification
Bcommercy inclura un en-tête X-Bcommercy-Signature dans chaque requête
Cette signature sera un hash HMAC-SHA256 du payload avec votre secret
Côté serveur, recalculez le hash et comparez-le pour valider l'authenticité

Bonnes pratiques

Utilisez HTTPS : Ne configurez jamais une URL en HTTP simple
Validez les données : Vérifiez toujours que les identifiants correspondent à des éléments réels
Répondez rapidement : Votre serveur doit répondre en moins de 5 secondes
Gérez les doublons : Un même événement peut être envoyé plusieurs fois en cas de nouvelle tentative

Gestion des erreurs et nouvelles tentatives

Si votre serveur ne répond pas correctement (code HTTP différent de 2xx), Bcommercy réessaiera automatiquement :

1ʳᵉ tentative : Immédiate
2ᵉ tentative : Après 5 minutes
3ᵉ tentative : Après 30 minutes
4ᵉ tentative : Après 2 heures
5ᵉ tentative : Après 24 heures

Après 5 échecs consécutifs, le webhook sera automatiquement désactivé. Vous recevrez une notification par email pour vous en informer.

Cas d'usage concrets

Notification SMS à chaque commande

Connectez votre webhook à un service comme Twilio ou Infobip pour recevoir un SMS instantané dès qu'une commande est passée – idéal pour ne jamais manquer une vente.

Synchronisation avec Google Sheets

Utilisez Zapier ou Make comme intermédiaire pour ajouter automatiquement chaque nouvelle commande dans un Google Sheets, parfait pour un suivi simplifié.

Mise à jour de stock dans un système externe

Si vous gérez votre inventaire dans un logiciel tiers, utilisez l'événement order.paid pour déclencher une mise à jour automatique des quantités.

Conclusion

Les webhooks seront un outil puissant pour automatiser votre activité et connecter Bcommercy à l'ensemble de votre écosystème technique. Voici les points essentiels à retenir :

Les webhooks sont des notifications push : vous recevrez l'information en temps réel
Sécurisez toujours vos endpoints avec HTTPS et la vérification de signature
Testez avant de mettre en production grâce à la fonction de test intégrée
Surveillez les logs pour identifier rapidement les problèmes de livraison
Gérez les doublons côté serveur pour éviter les traitements en double

Vous souhaitez être informé dès que les webhooks seront disponibles ? Contactez notre équipe technique. Consultez l'article « Comment contacter le support Bcommercy ? » pour nous joindre.