Configurer les webhooks
July 30, 2026
Configurez les webhooks FlowAlp Pay : réglages du dashboard, content types, plan de retry, timeout de 20 s, idempotence et confirmation fiable.
Les webhooks sont des notifications POST que FlowAlp Pay envoie à votre backend dès que le statut d'une transaction ou d'une subscription change ; les versements traités déclenchent aussi des notifications. C'est le moyen fiable de garder vos commandes synchronisées — la redirection du navigateur après le checkout ne l'est pas.
Créer un webhook dans le dashboard
Connectez-vous au dashboard sur https://pay.flowalp.com et ouvrez la section Webhooks. Pour chaque webhook, vous renseignez :
- Une URL HTTPS (ou adresse IP) accessible publiquement qui reçoit et traite les données
- Si les livraisons échouées doivent être retentées
- Le content type du payload
| Content type | Valeur d'en-tête | Quand le choisir |
|---|---|---|
| JSON | application/json | Recommandé pour presque tous les stacks |
| Normal (PHP-Post) | application/x-www-form-urlencoded | Traitement classique de type formulaire, p. ex. gestion directe de $_POST |
Retries et timeout
Avec le retry activé, la livraison est tentée jusqu'à 10 fois, jusqu'à ce que votre endpoint réponde avec succès :
| Tentative | Moment du déclenchement |
|---|---|
| 1 | Dès que possible — au plus 1 à 1,5 minute après la première tentative synchrone |
| 2 | 15 minutes après la tentative précédente |
| 3 | 1 heure après la tentative précédente |
| 4 | 2 heures après la tentative précédente |
| 5 | 4 heures après la tentative précédente |
| 6–10 | Toutes les 24 heures après la tentative précédente |
Votre endpoint doit répondre en 20 secondes, sinon la requête expire et le journal affiche le statut HTTP 0 avec un message de timeout. Répondez immédiatement 200 et déportez le travail lourd dans une file d'attente.
Réglages webhook des intégrations boutique
Quand vous activez une intégration e-commerce dans le dashboard (par exemple WooCommerce), elle enregistre son propre webhook vers votre boutique et apporte sa propre option de retry, avec des intervalles de 5 minutes, 15 minutes, 1 heure, 2 heures, 4 heures puis toutes les 24 heures. Saisissez l'URL de la boutique exactement : un écart de schéma comme http:// au lieu de https://, ou un sous-répertoire manquant, casse le traitement des webhooks.
Confirmer un checkout via webhook
- Créez le Gateway et stockez son ID avec votre
referenceId. - Recevez le webhook au changement de statut — voir événements et payloads.
- Vérifiez la signature avant de toucher au moindre état de commande.
- Rapprochez l'événement de la commande attendue via
referenceId(ou l'ID du lien de paiement dans les données d'invoice). - Récupérez la transaction via l'API si votre modèle de risque exige une deuxième source.
- Ensuite seulement, marquez la commande comme payée et exécutez-la.
N'utilisez jamais la seule redirection du navigateur vers la page de succès comme confirmation de paiement : les clients peuvent fermer le navigateur en cours de route et les URL peuvent être appelées directement.
Répondre correctement et rester idempotent
- Répondez avec un statut
2xxen moins de 20 secondes ; tout le reste compte comme une livraison échouée et déclenche les retries s'ils sont activés. - Le même événement peut arriver plusieurs fois — dédupliquez sur l'ID de transaction plus le statut avant d'agir.
- Traitez les événements de façon asynchrone et conservez un journal des payloads reçus et des résultats pour les audits.
Checklist de sécurité
- Exposez un endpoint webhook dédié, pas une route générique.
- Servez-le uniquement en HTTPS.
- Vérifiez les signatures des webhooks et rejetez les signatures invalides avec une réponse non-2xx.
- N'écrivez ni secrets ni payloads complets dans les journaux applicatifs généraux.
Étape suivante : étudiez les types d'événements et payloads que vous recevrez, puis mettez en place la vérification de signature.