Stripe
MakeWEBHOOKS STRIPE FIABLES
Prérequis
- Endpoint webhook Stripe configuré (test puis live) avec secret de signature
- Scénario Make avec module Webhooks custom ou relais via API Next.js
- Table Airtable « Stripe events » avec champ unique `event_id`
- Liste des événements métier retenus (`checkout.session.completed`, `invoice.paid`, etc.)
Stripe peut renvoyer le même événement plusieurs fois ; sans garde-fou, vous expédiez deux fois, facturez deux fois ou créez des doublons CRM. La vérification de signature, le stockage d’`event.id` et un scénario Make idempotent transforment les webhooks en file métier fiable.
Modèle webhook : vérifier puis router
Stripe envoie un POST JSON signé. Votre Route Handler lit le body brut, valide `Stripe-Signature` avec le webhook secret, puis parse l’événement typé.
Routez par `event.type` : paiement one-shot, abonnement, remboursement. Ignorez les types hors périmètre pour limiter la surface d’attaque et le bruit en monitoring.
En développement, `stripe listen --forward-to localhost:3000/api/webhooks/stripe` reproduit les événements sans exposer votre machine.
Idempotence avec Airtable ou base SQL
Stripe garantit au-least-once delivery : le même `event.id` peut arriver deux fois. Stockez chaque `event.id` traité avec statut, horodatage et payload résumé.
Pattern : insert event → si conflit unique, exit 200 sans effet. Pattern : lire commande, update, puis insert event : race condition possible.
Conservez aussi une clé métier (`payment_intent` ou `order_id`) pour corréler les événements différents d’une même transaction.
Relayer vers Make sans perdre d’événements
Option A : Make reçoit le webhook (module Webhooks). Validez la signature côté Next.js avant relais, ou logguez puis ack immédiat.
Option B : Next.js écrit en queue Airtable « pending », Make trigger sur nouvelle ligne. Plus traçable pour les PO.
Error handler Make vers Slack #ops avec `event_id` et lien Dashboard Stripe.
Erreurs fréquentes
Parser le JSON avant vérification signature : échec systématique en production.
Traitement synchrone lourd (génération PDF, sync ERP) dans le handler : timeouts Stripe et retries en cascade.
Absence de contrainte unique sur `event_id` : doublons CRM silencieux.
Webhook test et live partageant le même secret ou la même table sans colonne `mode`.
Ce qu’il faut retenir
Vérifier la signature, répondre 200 vite, traiter idempotent avec `event.id`.
Make ou Airtable comme couche de reprise et d’observabilité métier.
Documenter les `event.type` écoutés et le mapping statuts commande.
Tester les renvois manuels depuis le Dashboard Stripe avant go-live.
FAQ
Non. Limitez-vous aux types qui changent un statut métier (paiement confirmé, abonnement annulé, remboursement). Souscrivez uniquement à ces types dans le Dashboard pour réduire le volume.
Créez la commande en statut « pending payment » avant la redirection Checkout. Sinon, mettez le webhook en retry court jusqu’à trouver la commande via `metadata.order_id`. Logguez les événements orphelins pour diagnostic.
Possible pour des stacks légères, mais la vérification de signature est plus robuste dans votre API avec le SDK Stripe. Make peut prendre le relais après validation serveur. Conservez toujours une clé webhook secrète hors scénario Make.
