Introduction
Les webhooks sont l'épine dorsale des intégrations modernes : ils alimentent l'automatisation en temps réel, réduisent le travail manuel et améliorent la transparence entre commerçants, partenaires et systèmes de facturation. Pour les opérateurs de programmes partenaires, la synchronisation fiable des événements de conversion, la préparation des paiements et l'exécution des paiements sont particulièrement critiques. Cet article présente des flux de travail webhook pragmatiques avec Affilentra — incluant des modèles de payload et des indications d'intégration pour les systèmes comptables, les prestataires de paiement et les ERP internes.
Pourquoi les webhooks avec Affilentra ?
Affilentra propose une plateforme d'affiliation self‑hosted avec des rôles clairement séparés (opérateur logiciel, commerçant, partenaire). Les webhooks permettent ici de livrer automatiquement des événements du programme partenaire vers des systèmes externes : conversions validées, listes de paiement préparées et mises à jour de statut. Grâce à l'architecture self‑hosted, les commerçants conservent la souveraineté des données et peuvent héberger eux‑mêmes les endpoints webhook ou les intégrer dans une middleware existante.
Types d'événements essentiels et leur utilisation
Les événements suivants constituent la base de flux de travail pragmatiques :
- conversion.created – un événement de suivi a été enregistré et validé.
- conversion.updated – changements de statut (par ex. chargeback, remboursement, conversion confirmée).
- payout.prepared – une liste de paiement ou une entrée de paiement a été créée pour la facturation.
- payout.paid – le paiement a été transmis au prestataire de paiement ou marqué comme payé.
- accounting.export_ready – les données pertinentes pour la comptabilité sont prêtes à l'export (par ex. comme écritures comptables ou CSV).
- erp.update_required – changement de statut à répercuter dans l'ERP interne (par ex. statut de traitement ou de facture).
Modèles de payload (exemples)
Les payloads suivants servent de modèles pour l'intégration. Adaptez les champs à votre schéma interne et ne traitez que les champs dont vous avez besoin.
conversion.created (exemple)
{
"event": "conversion.created",
"timestamp": "2026-11-04T10:15:30Z",
"conversion": {
"id": "conv_12345",
"merchant_id": "m_987",
"partner_id": "p_456",
"offer_id": "o_22",
"amount": 149.90,
"currency": "EUR",
"status": "pending_validation",
"meta": { "order_ref": "ORD-20261104-001" }
}
}
payout.prepared (exemple)
{
"event": "payout.prepared",
"timestamp": "2026-11-04T11:00:00Z",
"payout": {
"id": "po_20261104_01",
"merchant_id": "m_987",
"partner_id": "p_456",
"gross_amount": 320.00,
"fees": 5.00,
"net_amount": 315.00,
"currency": "EUR",
"payout_method": "bank_transfer",
"batch_id": "batch_20261104",
"entries": [ { "conversion_id": "conv_12345", "amount": 120.00 }, { "conversion_id": "conv_12346", "amount": 200.00 } ]
}
}
payout.paid (exemple)
{
"event": "payout.paid",
"timestamp": "2026-11-04T12:30:00Z",
"payout": {
"id": "po_20261104_01",
"paid_at": "2026-11-04T12:28:00Z",
"transaction_id": "txn_7890",
"provider_status": "settled"
}
}
accounting.export_ready (exemple)
{
"event": "accounting.export_ready",
"timestamp": "2026-11-04T12:35:00Z",
"export": {
"id": "exp_20261104_01",
"format": "csv",
"records": [ { "account_code": "8400", "debit": 0, "credit": 315.00, "description": "Affiliate Payout" } ]
}
}
Flux d'intégration typiques
1) Conversion → préparation comptable
Flux : conversion.created → conversion.updated (confirmé) → accounting.export_ready.
- Lors de conversion.created : stockez un enregistrement minimal dans la couche intermédiaire et effectuez des validations (par ex. doublons, références CVR/commande).
- Lors de conversion.updated avec le statut confirmed : créez l'écriture comptable (client, chiffre d'affaires, TVA) ou marquez la conversion pour inclusion dans le prochain export.
- Lors de accounting.export_ready : générez le CSV/DATEV/JSON et déposez-le dans le répertoire comptable ou envoyez-le par SFTP à votre expert-comptable.
2) Préparation des paiements → fournisseur de paiement
Flux : payout.prepared → API du fournisseur de paiement → payout.paid.
- payout.prepared : constituez un lot avec les entrées de paiement, vérifiez les limites et la disponibilité (solde, statut KYC).
- Envoyez le lot à votre fournisseur de paiement ; utilisez des appels idempotents et fournissez la batch_id comme référence.
- Recevez le retour du fournisseur, marquez les transactions et attendez l'événement payout.paid pour l'écriture comptable finale.
3) Synchronisation ERP pour le fulfilment et le statut des factures
Flux : conversion.updated / erp.update_required → API ERP.
- En cas de changement de statut (par ex. fulfilled, refunded), Affilentra envoie un événement erp.update_required.
- Mapping : external_reference → numéro de commande ERP ; mettez à jour le statut de fulfilment, les numéros de facture et l'état des paiements.
- Bonnes pratiques : utilisez des acquittements par lot, limitez le débit et vérifiez l'unicité des références.
Bonnes pratiques pour des intégrations robustes
- Sécurité : Signez les payloads des webhooks avec HMAC (SHA256) et vérifiez les timestamps pour empêcher les attaques par rejeu.
- Idempotence : Traitez plusieurs fois la même event_id sans effets secondaires. Utilisez des clés d'idempotence dédiées.
- Gestion des erreurs : Implémentez une logique de retry avec exponential backoff ; consignez centralement les livraisons échouées.
- Versioning : Introduisez un champ de version de schéma d'événement pour maintenir la compatibilité lors des changements de schéma.
- Batching : Envoyez des événements agrégés pour la comptabilité et les paiements (p. ex. batch_id) afin de réduire l'effort et la latence.
- Minimisation des données utiles : Envoyez uniquement les champs dont les systèmes cibles ont besoin ; externalisez les métadonnées supplémentaires de façon optionnelle.
- Monitoring : Surveillez les taux de livraison, la latence et le taux d'erreur ; notifiez les responsables en cas de panne.
Notes par rôle
- Marchand (Merchant) : Définissez les endpoints de webhook, choisissez les événements et définissez les méthodes de paiement. L'auto‑hébergement permet un contrôle complet des flux de données.
- Partenaire (Publisher) : Bénéficiez de liens de tracking traçables et de notifications d'état de paiement transparentes, qui peuvent être transmises via webhooks aux tableaux de bord ou aux outils comptables.
- Opérateur logiciel : Fournissez des signatures sécurisées, de la documentation et du monitoring ; proposez des modèles et des exemples de mapping pour les prestataires comptables et de paiement courants.
Exemples pratiques : étapes d'implémentation
- Définissez les événements pertinents et un ensemble minimal de champs requis (p. ex. conversion_id, amount, currency).
- Mettez en place une middleware ou un petit service de réception qui valide les webhooks, déduplique et achemine vers les systèmes cibles.
- Implémentez des signatures HMAC et vérifiez les timestamps dans une fenêtre courte (p. ex. 5 minutes).
- Testez avec des événements simulés : conversion.created → payout.prepared → payout.paid → accounting.export_ready.
- Documentez les codes d'erreur et les processus de récupération pour vos équipes Finances et Opérations.
Conclusion et prochaine étape
Avec Affilentra, les flux de travail webhook pour le suivi des conversions, la préparation des paiements et les exports comptables peuvent être mis en œuvre de manière pratique et sécurisée — notamment dans des scénarios auto‑hébergés où le contrôle et la confidentialité des données sont centraux. La combinaison de schémas d'événements clairs, d'un traitement idempotent et de batches de paiements contrôlés réduit le travail manuel et augmente la transparence pour les marchands et les partenaires.
Prêt à utiliser les webhooks en production ? Choisir un démarrage
Prochaine étape
Essayer Affilentra
Plateforme unifiée qui rassemble de manière transparente la mise à disposition des produits, le suivi (tracking), la validation des conversions, le calcul des commissions et les paiements selon des rôles clairement séparés; option d'installation self-hosted avec licence perpétuelle sans participation au chiffre d'affaires; les commerçants conservent le contrôle sur les produits, les conditions et les supports publicitaires; les partenaires reçoivent des liens de suivi personnels et un historique de paiements consultable.