> ## Documentation Index > Fetch the complete documentation index at: https://docs.i-pay.money/llms.txt > Use this file to discover all available pages before exploring further. # Webhooks > Recevez et sécurisez les notifications de changement d'état. Les webhooks permettent à iMoney Encaissement d'envoyer automatiquement une notification à votre application lorsqu'un paiement change d'état. Utilisez-les pour mettre à jour une commande, synchroniser un back-office ou déclencher un traitement interne sans interroger l'API en continu. Un webhook est un complément à la consultation de statut, pas un remplacement : la notification vous prévient dès qu'un état change, tandis que [Consulter une transaction](/api-reference/transactions#get-payments-reference) donne le statut à l'instant de l'appel et sert de secours ou de réconciliation. ## Créer un webhook Depuis le tableau de bord marchand, ouvrez **Développeurs**, puis **Webhooks**. Cliquez ensuite sur **Ajouter** pour enregistrer un nouveau webhook. Le formulaire demande les informations suivantes : | Champ | Description | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **URL** | URL de votre endpoint de réception. Si le protocole n'est pas renseigné, iMoney Encaissement ajoute automatiquement `https://`. | | **Hash secret** | Valeur que **vous** définissez. iMoney Encaissement la renvoie telle quelle dans l'en-tête `Secret-Hash` de chaque notification, pour que votre serveur la compare à ce que vous avez configuré ici. | | **Événements créés** | Active les notifications `payment_created`. | | **Événements en attente** | Active les notifications `payment_pending`. | | **Événements réussis** | Active les notifications `payment_succeeded`. | | **Événements échoués** | Active les notifications `payment_failed`. | | **Événements remboursés** | Active les notifications `payment_refunded`. | Vous pouvez activer un ou plusieurs événements sur le même webhook. Seuls les événements cochés sont envoyés à l'URL configurée. > **Important — nature du `Secret-Hash` :** ce n'est **pas** une signature calculée à partir du corps de la notification (pas de HMAC, pas de hash du payload). C'est un secret partagé statique : vous choisissez sa valeur en créant le webhook, et iMoney Encaissement se contente de la recopier telle quelle dans l'en-tête `Secret-Hash` à chaque envoi. Votre serveur doit simplement comparer la valeur reçue à celle que vous avez configurée — il n'y a rien à recalculer. > **Attention :** ne partagez jamais le hash secret de votre webhook. C'est la seule information qui permette à votre serveur de vérifier qu'une notification provient bien de iMoney Encaissement plutôt que d'un tiers qui aurait deviné votre URL. Après avoir choisi les événements à recevoir, cliquez sur **Enregistrer**. ## Événements disponibles Cinq événements existent, tous liés au cycle de vie d'un paiement : | Événement | Quand il est envoyé | | ------------------- | -------------------------------------- | | `payment_created` | Le paiement vient d'être créé. | | `payment_pending` | Le paiement passe à l'état en attente. | | `payment_succeeded` | Le paiement est validé avec succès. | | `payment_failed` | Le paiement échoue. | | `payment_refunded` | Le paiement est remboursé. | Il n'existe pas d'autre événement que ces cinq : n'activez que ceux dont votre intégration a réellement besoin. ## Recevoir une notification Lorsqu'un événement actif se produit, iMoney Encaissement envoie une requête `POST` vers votre URL avec un corps JSON et les en-têtes suivants : ```http theme={null} Content-Type: application/json Accept: application/json Secret-Hash: votre_hash_secret ``` Votre endpoint doit : 1. vérifier que `Secret-Hash` correspond bien à la valeur configurée dans le dashboard ; 2. traiter le corps JSON ; 3. retourner une réponse HTTP `2xx` pour confirmer la bonne réception. Les réponses hors `2xx` et les erreurs réseau (timeout, endpoint injoignable) sont enregistrées dans l'historique du webhook. ## Format du payload Toutes les notifications utilisent la même structure de base : ```json theme={null} { "data": { "external_reference": "ORDER-2026-001", "reference": "ipay_ref_123", "status": "succeeded", "msisdn": "97000000", "net_amount": 950, "amount": 1000, "failure_reason": null, "customer_name": "Client Demo", "payment_method": "credit_card", "validated_at": "2026-06-04T10:30:00.000Z" } } ``` ### Champs du payload | Champ | Description | | -------------------- | ----------------------------------------------------------------------------------------------------------- | | `external_reference` | Référence envoyée par votre système lors de la création du paiement (votre `transaction_id`). | | `reference` | Référence interne iMoney Encaissement du paiement. | | `status` | Statut actuel du paiement : `initiated`, `pending`, `succeeded`, `failed` ou `refunded`. | | `msisdn` | Numéro de paiement du client. | | `net_amount` | Montant net après frais. | | `amount` | Montant brut du paiement. | | `failure_reason` | Raison de l'échec lorsque le paiement a échoué, sinon `null`. | | `customer_name` | Nom du client lorsque l'information est disponible. | | `payment_method` | Moyen de paiement utilisé — voir les [moyens de paiement](/guides/reversement#frais-par-moyen-de-paiement). | | `validated_at` | Date de validation du paiement lorsque disponible, sinon `null`. | Selon l'origine du paiement, iMoney Encaissement peut aussi ajouter les champs suivants — ils ne sont **pas** présents sur toutes les notifications : | Champ conditionnel | Présent quand | | ---------------------------- | ----------------------------------------------------------------------------------- | | `dynamic_payment_reference` | Le paiement est rattaché à un paiement dynamique. | | `external_payment_reference` | Le paiement est rattaché à un [lien de paiement](/api-reference/liens-de-paiement). | Sur un paiement échoué, `failure_reason` porte le motif du refus lorsqu'il est fourni et `validated_at` reste `null` ; les valeurs possibles de `status` et le contrat complet des champs d'un paiement (types, contraintes) sont décrits dans [Consulter une transaction](/api-reference/transactions#get-payments-reference). ## Comportement de nouvel essai iMoney Encaissement envoie la notification **une fois** dès que l'événement se produit, puis programme dix minutes plus tard un envoi de rattrapage. Ce rattrapage ne part que si **aucune tentative d'envoi n'a été enregistrée** pour cet événement. Or une tentative est enregistrée dans les deux cas : quand votre serveur a répondu, et quand l'envoi a échoué (endpoint injoignable, réponse hors `2xx`, timeout). Ce qu'il faut en retenir : * **un envoi qui échoue n'est pas rejoué** : le rattrapage de dix minutes ne couvre que le cas où aucun envoi n'a eu lieu, pas celui d'un envoi qui s'est mal passé ; * il n'existe **pas** de relances illimitées ni de nombre de tentatives configurable ; * dès lors qu'une tentative a échoué, votre application ne recevra plus de notification pour cet événement et doit se rabattre sur [Consulter une transaction](/api-reference/transactions#get-payments-reference) pour connaître le statut définitif. Ne considérez donc jamais l'absence de webhook comme une absence de changement d'état, et ne bâtissez pas votre intégration sur l'idée qu'un échec sera rattrapé : réconciliez systématiquement par consultation API, en particulier pour les paiements restés `pending` plus longtemps qu'attendu. C'est la consultation, et non la notification, qui fait foi. ## Consulter l'historique La page **Webhooks** affiche les webhooks configurés avec leur URL, les événements actifs, leur date de création et les actions disponibles. Pour chaque webhook, le bouton **Logs** permet de consulter l'historique des tentatives d'envoi, y compris l'envoi de rattrapage le cas échéant. L'historique affiche : * la référence du paiement ; * l'événement envoyé ; * le statut HTTP retourné par votre serveur ; * le corps de la requête envoyée ; * la réponse retournée par votre serveur ; * la date d'envoi. Le détail d'un log permet de vérifier le payload complet et les informations du paiement concerné. ## Bonnes pratiques * Utilisez une URL HTTPS publique et stable. * Vérifiez toujours l'en-tête `Secret-Hash` avant de traiter la notification — c'est une comparaison directe avec la valeur que vous avez configurée, pas un calcul cryptographique. * Retournez rapidement une réponse HTTP `2xx` après réception, avant de lancer un traitement long. * Rendez votre traitement idempotent en utilisant la référence iMoney Encaissement `reference` : ne traitez pas deux fois le même événement si une notification vous parvient en double. * Ne dépendez pas de l'ordre exact des notifications : vérifiez toujours le `status` reçu plutôt que de supposer une séquence. * N'attendez pas indéfiniment un webhook qui n'arrive jamais : réconciliez les paiements restés en attente avec [Consulter une transaction](/api-reference/transactions#get-payments-reference). Éprouvez ces règles en Sandbox avant la production : les numéros de test qui produisent un paiement réussi, un échec ou une mise en attente — donc les événements correspondants — sont listés dans la [section Sandbox](/api-reference/transactions#sandbox) de la fiche Transactions. Une fois votre URL de webhook éprouvée en Sandbox, reconfigurez-la sur votre compte Live en suivant [Passer en production](/demarrer/mise-en-route#passer-en-production).