Configurer les webhooks

Un webhook est une requête POST qu'Integral Pay envoie à votre serveur à chaque changement de statut d'un paiement (événement payment.updated). C'est la source fiable pour valider une commande : il arrive même si votre client ferme son navigateur avant la fin du paiement.

1. Déclarer votre adresse de réception

Depuis votre espace (rubrique Webhooks) ou par l'API :

Python

create_webhook.py

resp = session.post(f"{API_BASE}/webhooks/", json={
    "url": "https://boutique.bf/integralpay/webhook/",
    "event_types": ["payment.updated"],
}, timeout=30)
resp.raise_for_status()
secret = resp.json()["secret"]   # affiché UNE seule fois : enregistrez-le maintenant

cURL

terminal

curl -X POST https://integralpay.tech/api/v1/webhooks/ \
  -H "X-Api-Key: $INTEGRALPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://boutique.bf/integralpay/webhook/", "event_types": ["payment.updated"]}'

La réponse contient le secret de signature (secret) et un avertissement : c'est la seule fois où il est affiché. Enregistrez-le sur votre serveur, par exemple dans INTEGRALPAY_WEBHOOK_SECRET. Il sert à vérifier la signature de chaque webhook.

Règles de l'adresse :

• https:// obligatoire, avec un certificat valide ;
• adresse publique uniquement (localhost, adresses privées et réseaux internes sont refusés) ;
• port par défaut (443), ou 80, 8080, 8443 ;
• pas d'identifiant ni de mot de passe dans l'adresse ;
• les redirections ne sont pas suivies : l'adresse doit répondre elle-même.

2. Recevoir les webhooks

Votre adresse doit, dans l'ordre :

1. vérifier la signature et refuser tout webhook invalide ;
2. répondre 200 en moins de 10 secondes ;
3. traiter l'événement une seule fois, même s'il arrive deux fois (idempotence).

Le contenu de chaque webhook est décrit dans Contenu des webhooks.

3. Tester

POST /api/v1/webhooks/{id}/test/ (ou l'action « Envoyer un webhook de test » de votre espace) envoie un webhook avec "test": true et l'identifiant de paiement 00000000-0000-0000-0000-000000000000. Votre serveur doit vérifier sa signature, puis l'ignorer.

Relances automatiques

Sans réponse 2xx dans les 10 secondes, l'envoi est considéré comme échoué et relancé :

Tentative	Envoyée
1	Au changement de statut du paiement
2	5 minutes après l'échec précédent
3	10 minutes après
4	20 minutes après
5	40 minutes après ; au-delà, l'envoi est abandonné

Une fois votre serveur réparé, relancez les envois abandonnés depuis votre espace (rubrique Webhooks, livraisons, action « Rejouer les livraisons sélectionnées »).

Gérer vos adresses

Action	Requête
Lister	GET /api/v1/webhooks/ (secret masqué)
Consulter	GET /api/v1/webhooks/{id}/
Modifier l'adresse ou les événements, désactiver	PATCH /api/v1/webhooks/{id}/ avec url, event_types ou is_active
Envoyer un webhook de test	POST /api/v1/webhooks/{id}/test/
Renouveler le secret	Depuis votre espace connecté uniquement (voir ci-dessous)

Renouveler le secret

Si le secret a pu fuiter (départ d'un développeur, fichier de configuration publié par erreur), renouvelez-le depuis votre espace : action « Renouveler le secret de signature ». Le nouveau secret s'affiche une seule fois, et l'ancien cesse immédiatement de fonctionner : mettez à jour votre serveur dans la foulée, sinon votre propre vérification refusera les webhooks suivants.

Pour des raisons de sécurité, ce renouvellement exige une connexion à votre espace : une clé API volée ne doit pas permettre d'obtenir un secret valide.