Référence des événements

Chaque événement est un objet JSON contenant un type, un ID unique et les données de la ressource concernée. Abonnez-vous à ces événements lors de la création d’un endpoint webhook.

Les événements sont émis en mode livemode: true en production et livemode: false en sandbox. Un même endpoint ne reçoit que les événements du mode correspondant à sa clé API.

Idempotence — traitez chaque événement une seule fois

En cas de retry, le même événement peut être livré plusieurs fois avec le même id. Stockez les IDs d’événements déjà traités et ignorez les doublons pour garantir l’idempotence de votre handler.

Événements Paiements

Événement	Déclencheur
`payment_intent.created`	PaymentIntent créé.
`payment_intent.succeeded`	Paiement réussi — déclencher la livraison.
`payment_intent.payment_failed`	Paiement échoué après la dernière tentative.
`payment_intent.canceled`	PaymentIntent annulé manuellement.
`checkout_session.completed`	Session checkout passée en statut `complete`.
`checkout_session.expired`	Session expirée sans paiement.
`transaction.succeeded`	Transaction finalisée côté opérateur.
`transaction.failed`	Transaction échouée côté opérateur.
`refund.created`	Remboursement initié.
`refund.succeeded`	Remboursement restitué à l'acheteur.
`refund.failed`	Remboursement échoué côté opérateur.
`payment_link.paid`	Lien de paiement utilisé avec succès.

Événements Clients

Événement	Déclencheur
`customer.created`	Nouveau Customer créé.
`customer.updated`	Données client modifiées.
`customer.deleted`	Customer anonymisé (conformité RGPD).
`payment_method.attached`	Méthode de paiement ajoutée au client.
`payment_method.detached`	Méthode de paiement retirée du client.

Événements Abonnements

Événement	Déclencheur
`subscription.created`	Nouvel abonnement créé.
`subscription.updated`	Abonnement modifié (plan, quantité…).
`subscription.renewed`	Renouvellement réussi — facture réglée.
`subscription.past_due`	Échec de renouvellement — déclencher relance.
`subscription.canceled`	Résiliation effective.
`subscription.trial_will_end`	3 jours avant la fin de la période d'essai.
`invoice.created`	Facture générée automatiquement.
`invoice.finalized`	Facture finalisée et envoyée au client.
`invoice.paid`	Facture réglée.
`invoice.payment_failed`	Échec de paiement de la facture.

Événements Compte

Événement	Déclencheur
`kyc.submitted`	Dossier KYC soumis pour validation.
`kyc.approved`	KYC validé — compte pleinement opérationnel.
`kyc.rejected`	KYC rejeté — action requise du marchand.
`payout.created`	Virement vers le compte bancaire initié.
`payout.paid`	Virement effectué avec succès.
`payout.failed`	Virement échoué — vérifier les coordonnées bancaires.

La liste des événements est-elle complète ?

Structure d’un événement

Response Objet Event

Structure commune à tous les événements Sangho.

json

{
  "id": "evt_xxxxxxxxxxxx",
  "object": "event",
  "type": "payment_intent.succeeded",
  "api_version": "v1",
  "created_at": "2026-03-01T10:05:00Z",
  "livemode": true,
  "data": {
    "object": {
      "id": "pi_xxxxxxxxxxxx",
      "object": "payment_intent",
      "amount": 15000,
      "currency": "XAF",
      "status": "succeeded",
      "customer": "cus_xxxx"
    }
  }
}

Implémenter un handler

Votre handler webhook doit répondre avec un code HTTP 2xx dans les 10 secondes. Pour les traitements longs, enfilez la tâche dans une queue asynchrone et répondez immédiatement.

Commencez toujours par vérifier la signature Sangho-Signature avant tout traitement. Consultez le guide de vérification de signature pour les exemples complets par langage.

Gestion des événements inconnus

Votre handler doit ignorer silencieusement les types d’événements qu’il ne reconnaît pas et retourner un 200. Sangho peut émettre de nouveaux types d’événements sans préavis — un handler qui retourne une erreur sur un type inconnu sera mis en retry inutilement.

Événement de test

Utilisez POST /webhooks/{id}/test/ pour envoyer un événement fictif à votre endpoint et valider votre intégration sans déclencher un vrai paiement. L’événement de test a livemode: false quel que soit l’environnement.

Les exemples d'implémentation sont-ils utiles ?

Gestionnaire Webhook

javascript

// Node.js / Express
app.post(
  '/webhook',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const sig = req.headers['sangho-signature'];
    let event;


    try {
      event = sangho.webhooks.constructEvent(
        req.body,
        sig,
        process.env.WEBHOOK_SECRET,
      );
    } catch (err) {
      return res.status(400).send(`Signature invalide: ${err.message}`);
    }


    switch (event.type) {
      case 'payment_intent.succeeded':
        await fulfillOrder(event.data.object.metadata.order_id);
        break;
      case 'subscription.past_due':
        await sendDunningEmail(event.data.object.customer);
        break;
      case 'refund.succeeded':
        await notifyCustomerRefund(event.data.object);
        break;
      default:
        // Type inconnu — ignorer silencieusement
        break;
    }


    res.json({ received: true });
  },
);