> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fapshi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Intégration Webhook

> Découvrez comment intégrer des webhooks pour recevoir en temps réel les mises à jour du statut des paiements depuis Fapshi.

Un webhook est un **point de terminaison API** mis à disposition des applications externes, qui peut être appelé pour notifier votre application lorsqu’un événement important se produit. Cela permet à votre application de réagir immédiatement à ces événements.

Vous pouvez définir une URL de webhook **par service** dans votre tableau de bord Fapshi. Lorsqu’un webhook est défini, une requête **POST** sera envoyée à cette URL chaque fois que le statut d’un paiement change en :

* **SUCCESSFUL** — lorsqu’un paiement est effectué avec succès
* **FAILED** — lorsqu’une tentative de paiement échoue (généralement sur les réseaux MTN Mobile Money ou Orange Money)
* **EXPIRED** — lorsqu’un lien de paiement expire après 24 heures sans paiement réussi

Le corps de la requête webhook est identique au corps de la réponse retournée par la [requête de statut de paiement](/fr/api-reference/endpoint/payment-status).

## Comment fonctionnent les webhooks

<img src="https://mintcdn.com/fapshi/rsmiGbzLVUpOYdAW/images/api-references/webhook-sequence-diagram.png?fit=max&auto=format&n=rsmiGbzLVUpOYdAW&q=85&s=50194b5abad7f5e966ef9a3dc6ff5931" alt="Schéma de séquence webhook" width="2816" height="1536" data-path="images/api-references/webhook-sequence-diagram.png" />

1. **Paiement initié** : Votre application externe initie un paiement en appelant l'un des endpoints de paiement Fapshi (par ex. [initiate-pay](/fr/api-reference/endpoint/initiate-pay) ou [direct-pay](/fr/api-reference/endpoint/direct-pay)).

2. **Paiement traité** : Le serveur Fapshi traite la transaction. Cela inclut le flux de paiement, la communication avec les opérateurs et la mise à jour du statut de la transaction.

3. **Webhook envoyé** : Lorsque le statut du paiement passe à SUCCESSFUL, FAILED ou EXPIRED, le serveur Fapshi envoie automatiquement une requête POST à votre URL de webhook avec les détails de la transaction mis à jour.

4. **Webhook reçu** : Votre application reçoit la notification webhook et peut la traiter (par ex. mettre à jour votre base de données, envoyer des notifications, déclencher d'autres flux).

<Note>
  Votre serveur doit répondre rapidement aux requêtes webhook pour éviter les erreurs de timeout, idéalement avec un code de statut 200. Fapshi n’envoie qu’une seule requête webhook par événement, **même si votre serveur ne répond pas**.
</Note>

## Sécurité des webhooks

Vous pouvez authentifier l’origine d’une requête webhook en définissant un secret webhook sur le tableau de bord Fapshi. Lorsqu’un secret est configuré, chaque requête webhook inclut un en-tête appelé `x-wh-secret` dont la valeur est le secret défini sur le tableau de bord. Comparer la valeur de cet en-tête au secret que vous avez configuré permet de vérifier si la requête provient de Fapshi.

Par mesure de sécurité, le tableau de bord ne permet pas de consulter ni de savoir si un secret webhook a déjà été défini pour un service.

## Format de la requête webhook


## OpenAPI

````yaml /fr/api-reference/openapi.json WEBHOOK /webhook/payment-status
openapi: 3.1.0
info:
  title: API de Paiement Fapshi
  description: >-
    API pour générer des liens de paiement, des paiements directs, la
    surveillance des transactions, les retraits, et plus encore.
  version: 1.0.0
servers:
  - url: https://sandbox.fapshi.com
security:
  - apiAuth: []
    apiKey: []
paths: {}
components:
  securitySchemes:
    apiAuth:
      type: apiKey
      in: header
      name: apiuser
    apiKey:
      type: apiKey
      in: header
      name: apikey

````