Événements webhook

Événements émis

Événement	Description
`payment.success`	Paiement confirmé
`payment.failed`	Paiement échoué
`payment.pending`	Paiement en attente de confirmation opérateur
`payment.expired`	Paiement expiré (délai écoulé, `POST /v1/payments/{id}/expire` ou réconciliation)
`payment.updated`	Autre changement de statut
`invoice.created`	Facture d’échéance d’abonnement créée (avec `payment_url`)
`subscription.payment_due`	Échéance d’abonnement (compatibilité, avec `payment_url`)
`invoice.paid`	Facture réglée
`subscription.renewed`	Abonnement prolongé après paiement
`refund.pending`	Remboursement demandé, en cours de traitement
`secure_order.paid`	Commande sécurisée payée, fonds en séquestre
`secure_order.released`	Livraison confirmée, fonds libérés
`secure_order.refunded`	Commande remboursée à l’acheteur
`secure_order.disputed`	Litige ouvert par l’acheteur
`secure_order.cancelled`	Commande annulée avant paiement
`webhook.test`	Test de connectivité

Le catalogue à jour est renvoyé par GET /v1/webhook-event-types. Un endpoint sans type choisi reçoit tous les événements ; ignorez ceux que vous ne gérez pas.

payment.cancelled figure au catalogue mais un paiement n’a pas de statut « annulé » : un abandon finit en payment.expired.

Enveloppe

{
  "id": "evt_4b1d9c0e7f2a6b3c5d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c",
  "event": "payment.success",
  "version": "v1",
  "timestamp": "2026-10-03T10:05:00.000Z",
  "livemode": false,
  "application": "2f6c1e9a-...",
  "data": { }
}

id est stable pour un même événement : dédupliquez dessus. livemode indique le mode (test ou live) de l’objet. Le contenu de data pour les paiements est détaillé dans le guide webhooks.

Headers

Header	Description
`X-SahelPay-Signature`	`t=<timestamp>,v1=<signature>`
`X-SahelPay-Timestamp`	Timestamp UNIX (secondes)
`X-SahelPay-Event-ID`	ID unique de l’événement
`X-SahelPay-Signature-Algorithm`	`HMAC-SHA256`
`X-Request-ID`	Identifiant de corrélation
`Content-Type`	`application/json`

Retry automatique

Tentative	Délai
1	Immédiat
2	1 minute
3	2 minutes
4	4 minutes
5	8 minutes