Configurer votre webhook

Un webhook est une requête HTTP POST que Cartflox envoie à votre serveur à chaque changement de statut d’un paiement. C’est la façon fiable de valider une commande.

Depuis le tableau de bord

Dans API et Logs, renseignez l’URL de réception. Elle doit être publique et en HTTPS : les adresses locales et les réseaux privés sont refusés.

Par l’API

GET/v1/config/webhookLire l'URL configurée

PATCH/v1/config/webhookDéfinir ou changer l'adresse, choisir les événements

Champ	Type	Description
webhookUrl	string	Adresse publique en https. Une chaîne vide retire le webhook.
mode	string	live (défaut avec une clé de production) ou test : quelle adresse on règle. Voir Mode test.
events	string[]	Les événements à recevoir, parmi ceux listés dans Événements. Absent ou complet : tous.

curl

curl -X PATCH https://cartflox.com/api/v1/config/webhook \
  -H "Authorization: Bearer af_live_sec_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "webhookUrl": "https://maboutique.com/webhooks/cartflox", "events": ["payment.completed", "payment.failed", "payment.cancelled"] }'

200 OK

{
  "success": true,
  "webhookUrl": "https://maboutique.com/webhooks/cartflox",
  "testWebhookUrl": null,
  "events": ["payment.completed", "payment.failed", "payment.cancelled"],
  "available_events": ["payment.completed", "payment.failed", "payment.cancelled", "payment.updated", "transfer.succeeded", "transfer.failed"]
}

Livraison et nouvelles tentatives

• Délai d’attente : 10 secondes. Répondez 2xx immédiatement et traitez ensuite.
• En cas d’échec (erreur réseau, réponse non 2xx, délai dépassé) : jusqu’à 10 tentatives sur environ 72 heures (1 min, 5 min, 15 min, 1 h, 3 h, 6 h, 12 h, 24 h, 24 h), puis une notification dans votre tableau de bord.
• Chaque envoi est journalisé et se renvoie à la main : Journal et rejeu.
• Le même événement peut donc arriver deux fois, par exemple si votre serveur a répondu trop tard : rendez votre traitement idempotent, en vous appuyant sur l’en-tête X-Afriflow-Delivery, ou sur data.id et data.status.
• Un webhook manqué se rattrape aussi en interrogeant le statut de la session.