Webhooks qui attendent : budgets de latence pour les événements synchrones
Stripe permet 2 secondes, Shopify 5. Découvrez comment mesurer la latence des sauts de tunnel, construire un budget de latence pour les webhooks et maintenir vos gestionnaires locaux rapides.

Quick answer
Budgets de latence des webhooks : Stripe 2 s et Shopify 5 s: webhook testing answer
For local webhook testing, run your app locally, expose it with a public HTTPS tunnel, and paste the stable callback URL into the provider dashboard.
How do I test webhooks on localhost?
Start your local server, open a public HTTPS tunnel to that port, configure the provider webhook URL, and inspect events in your local logs.
Why does a stable webhook URL matter?
Stable URLs prevent provider dashboards from needing manual callback updates every time you restart a tunnel.
La plupart des webhooks sont polis. Un fournisseur envoie un événement, votre serveur répond « c’est noté », et tout le reste se passe ensuite. Certains webhooks ne sont pas du tout polis. Ils arrêtent une vraie transaction et attendent que vous fassiez.
Si vous développez ces gestionnaires sur un ordinateur portable derrière un tunnel, vous avez un nouveau problème : l’horloge tourne déjà et le saut par le tunnel n’en représente qu’une tranche. Ce guide décrit les budgets actuels, comment mesurer combien de chaque budget votre tunnel consomme, et comment garder un gestionnaire local suffisamment rapide pour tester votre logique et non votre chance.
Les deux budgets qui comptent pour le moment
Stripe Issuing : 2 secondes, et la réponse est la décision
Lorsqu’une carte émise via Stripe Issuing est utilisée, Stripe vérifie que votre solde Issuing dispose de fonds, que la carte est active et que vos contrôles de dépenses autorisent l’achat. Si l’autorisation passe ces vérifications et que vous avez configuré un webhook d’autorisation en temps réel, Stripe envoie un événement issuing_authorization.request à votre point de terminaison. Si vous n’approuvez pas ou ne refusez pas dans les 2 secondes, Stripe approuve ou refuse l’autorisation pour vous, en fonction de vos paramètres de délai d’attente dans les paramètres Issuing du Dashboard, ou des paramètres Autopilot si vous les avez configurés.
Quatre détails des documents actuels influencent votre conception pour cela :
- La réponse est la décision. Vous répondez directement au webhook avec un statut
200et un corps JSON. Le champapprovedest requis. L’en-têteStripe-Versionest également requis sur la réponse, etapplication/jsonest le seul type de contenu accepté. - L’échec a un nom. Lorsque la
request_history.reasond’une autorisation estwebhook_errorouwebhook_timeout, Stripe ne reçoit pas vos réponses.webhook_errorsignifie que vous avez répondu avec une version de Stripe API invalide dans les en-têtes de requête, ou Stripe n’a pas pu traiter votre réponse.webhook_timeoutcouvre tous les autres modes d’échec. Stripe avertit également de ne pas utiliser le drapeauapprovedpour juger de la santé de l’intégration, car Autopilot peut approuver en votre nom en cas d’erreur. Son exemple d’un élément à examiner est une autorisation avecapproved: truemaisrequest_history.reason: webhook_error. Abonnez-vous àissuing_authorization.createdetissuing_authorization.updatedpour surveiller ces cas, et lisezrequest_history.reason_messagepour le texte d’erreur détaillé. - Les retours existent, mais ce n’est pas votre logique. Autopilot, actuellement en aperçu public, prend des décisions en votre nom à partir d’un ensemble prédéfini de règles lorsque vos systèmes sont en panne, ne répondent pas, ou retournent une réponse invalide. Vous le configurez en contactant le support Stripe. Un Autopilot Stripe distinct (également en aperçu public) est destiné aux utilisateurs avec leur BIN dédié. Il aide lorsque le réseau de carte ne peut pas atteindre Stripe, et ces décisions sont étiquetées
network_fallback. Aucun des deux ne remplace une réponse dans les délais. - Toutes les transactions ne vous arrivent pas. Seules les demandes d’autorisation vont vers le point de terminaison synchrone. Les autres notifications vont vers votre point de terminaison webhook habituel. Si votre solde Issuing est trop faible, l’autorisation est refusée et votre webhook ne voit jamais la requête. Les rejets liés au contrôle des dépenses se produisent aussi du côté de Stripe. Si vous n’avez pas de webhook en temps réel configuré, Stripe approuve les autorisations qui passent ses propres vérifications sans envoyer la requête.
Pourquoi cela devient soudainement le problème de tout le monde
La documentation Stripe Issuing for agents décrit donner à chaque agent sa propre carte virtuelle avec des plafonds de dépenses par agent, des contrôles par catégorie de marchands et des règles d’autorisation personnalisées. Elle indique aussi que, une fois que vous confiez une carte à un agent, chaque tentative d’achat déclenche une demande d’autorisation en temps réel avant que la charge ne passe. La même page indique qu’il existe un délai d’attente par défaut de 2 secondes pour répondre avant que Stripe ne retombe sur les règles par défaut de la carte.
Le guide Stripe sur le checkout programmatique ajoute une deuxième voie. Lorsqu’un vendeur échange un Shared Payment Token (SPT) financé par une carte Issuing, la charge passe par votre chemin d’autorisation en temps réel Issuing existant, avant la capture et le règlement. Ce guide dit que la création d’un PaymentMethod à partir d’une carte Issuing nécessite un accès en aperçu privé, et les demandes SPT utilisent la version d’API d’aperçu 2026-04-22.preview. Considérez ce flux comme quelque chose à vérifier par rapport à la documentation actuelle avant de le construire.
En d’autres termes, un agent achetant quelque chose devient désormais une source normale d’événements issuing_authorization.request, et chacun d’eux est une horloge de deux secondes.
Shopify : 5 secondes, et la réponse est un accusé de réception
La documentation de dépannage des webhooks de Shopify indique que votre application doit répondre dans les cinq secondes et qu’un statut de la série 200 compte comme succès. Ses conseils pour les gestionnaires lents consistent à retarder le traitement jusqu’à ce que vous ayez envoyé une réponse.
Les conséquences de manquer la fenêtre sont également détaillées :
- Shopify réessaie les livraisons échouées jusqu’à huit fois sur une période de quatre heures, et l’intervalle entre les tentatives suivantes augmente.
- Si les échecs persistent, l’abonnement est supprimé. Les abonnements supprimés ne reçoivent rien tant que vous ne les recréez pas.
- Le Dev Dashboard affiche votre temps de réponse au 90e percentile et votre taux de livraison échouée. Les taux d’échec supérieurs à 0,5 % sont décrits comme supérieurs à la moyenne. Les temps de réponse entre quatre et cinq secondes sont signalés comme dangereusement proches de la limite.
La différence entre les deux fournisseurs est le point de conception clé :
Stripe issuing_authorization.request |
Shopify webhooks | |
|---|---|---|
| Fenêtre | 2 secondes | 5 secondes |
| Ce que vous renvoyez | La décision elle-même | Un accusé de réception 2xx |
| Travail après avoir répondu | Pas possible pour la décision | Attendu, et recommandé |
| En cas d’échec | Vos paramètres de délai (ou Autopilot) décident | Réessaies jusqu’à 8 fois, puis suppression de l’abonnement |
Avec Shopify, vous pouvez tricher l’horloge en accusant réception rapidement et en travaillant plus tard. Avec Stripe Issuing, vous ne pouvez pas, car le travail que vous différeriez est ce que Stripe attend.
Anatomie d’un budget de 2 000 ms
Considérez la fenêtre comme un budget que vous dépensez, et non comme une limite à rester sous. Pour un webhook synchrone, le temps entre l’envoi de la requête par Stripe et la réception de votre réponse se décompose approximativement ainsi :
- De Stripe jusqu’au bord du tunnel (transit Internet, TLS)
- Du bord du tunnel à l’agent du tunnel sur votre machine (le tunnel lui-même)
- De l’agent à votre serveur local (loopback, essentiellement gratuit)
- Votre gestionnaire (analyse, vérification, logique de décision, entrées/sorties)
- Le même chemin de retour
Voici une allocation illustrative. Ce sont des chiffres de planification, et pas des mesures d’un service :
| Segment | Allocation prévisionnelle |
|---|---|
| Réseau entrant et TLS | 100–300 ms |
| Saut du tunnel, dans les deux sens | 50–200 ms |
| Vérification de signature et parsing | inférieur à 10 ms |
| Logique de décision | inférieur à 100 ms |
| Marge de sécurité | 800 ms ou plus |
Remarquez ce que le tableau implique. Si votre gestionnaire effectue une simple requête de base de données à froid ou un seul appel API sortant, vous pouvez brûler la marge sans le remarquer, et le tunnel n’en est pas la cause. Le seul moyen de le savoir est de mesurer.
Une règle utile consiste à fixer un délai interne bien en dessous de la fenêtre du fournisseur, par exemple 800 à 1 000 ms pour Stripe, et à faire en sorte que votre gestionnaire rende sa meilleure réponse d’ici là, quel que soit l’état de ses dépendances. Si vous décidez d’un délai personnel, vous choisissez la décision de repli. Si l’horloge de Stripe décide, les paramètres de votre Dashboard (ou Autopilot) la choisissent pour vous.
Mesurer le saut du tunnel
Vous ne pouvez pas soustraire ce que vous n’avez pas mesuré. Utilisez trois mesures et comparez-les.
1. Mesurer le temps du gestionnaire lui-même
Instrumentez votre code. C’est ce nombre que le tunnel ne peut pas influencer. Voici un exemple minimal avec Node et Express qui rapporte sa propre durée via l’en-tête standard Server-Timing :
import express from "express";
const app = express();
app.use(express.raw({ type: "application/json" }));
app.post("/stripe/issuing", (req, res) => {
const start = process.hrtime.bigint();
// 1. Vérifier l'en-tête Stripe-Signature contre req.body (les octets bruts),
// par exemple avec stripe.webhooks.constructEvent().
// 2. Exécuter votre logique de décision.
const decision = { approved: true };
const ms = Number(process.hrtime.bigint() - start) / 1e6;
console.log(JSON.stringify({ route: "issuing", handler_ms: ms }));
res.status(200);
res.set("Stripe-Version", "2025-03-31.basil"); // utiliser une version prise en charge, voir Stripe's API versioning docs
res.set("Server-Timing", `handler;dur=${ms.toFixed(1)}`);
res.json(decision);
});
app.listen(3000);
La valeur Stripe-Version ci-dessus est celle utilisée dans l’exemple propre de Stripe. Consultez la page de versionnage de l’API Stripe pour les valeurs prises en charge, car un en-tête de version invalide est une cause documentée de webhook_error. Les docs Stripe indiquent également de vérifier les signatures des webhooks et de mettre sur liste blanche les adresses IP de Stripe afin de n’agir que sur les événements Stripe authentiques.
2. Chronométrer la requête de bout en bout avec curl
curl peut décomposer une requête en plusieurs étapes. Chaque valeur est un horodatage cumulatif depuis le début de la requête :
curl -s -o /dev/null -X POST "https://YOUR-SUBDOMAIN.example-tunnel.dev/stripe/issuing" \\
-H "Content-Type: application/json" -d '{"test":true}' \\
-w 'dns=%{time_namelookup} connect=%{time_connect} tls=%{time_appconnect} first_byte=%{time_starttransfer} total=%{time_total}\\n'
Run the same command against http://localhost:3000/stripe/issuing. The gap between the two total values, taken over many runs, is your tunnel overhead as seen from your own position. For a handler that verifies signatures, an unsigned test request will be rejected early. Either add a test bypass or send a correctly signed payload.
3. Compare percentiles, not averages
A budget is broken by the slow tail, not the median. Run a couple of hundred requests each way and compare p50, p95 et p99:
URL="https://YOUR-SUBDOMAIN.example-tunnel.dev/stripe/issuing"
for i in $(seq 1 200); do
curl -s -o /dev/null -w '%{time_total}\n' -X POST "$URL" \\
-H "Content-Type: application/json" -d '{}'
done | sort -n | awk '{a[NR]=$1} END {print "p50="a[int(NR*0.50)], "p95="a[int(NR*0.95)], "p99="a[int(NR*0.99)]}'
Sachez ce que votre mesure n’inclut pas
Soyez honnête sur les limites des mesures côté portable. Lorsque vous appelez votre propre URL de tunnel depuis la même machine, la requête sort de votre réseau, atteint l’extrémité, et revient dans le tunnel jusqu’à vous. Ce trajet en épingle n’est pas celui emprunté par les serveurs de Stripe, il peut donc gonfler ou sous-estimer la latence entrante réelle. Deux façons de l’affiner :
- Exécutez la boucle
curldepuis une petite VM cloud dans une région proche de l’origine probable du fournisseur, afin que la jambe entrante ressemble à la réalité. - Enregistrez un horodatage de réception dans votre gestionnaire et comparez-le avec l’heure de création de l’événement elle-même. Les horodatages des événements Stripe sont en secondes entières et votre horloge peut être décalée, utilisez ceci uniquement pour repérer des retards grossiers, pas pour mesurer des millisecondes.
Utiliser les journaux de requêtes pour voir ce qui s’est réellement passé
Les mesures d’une boucle vous indiquent ce qui est possible. Les journaux de requêtes indiquent ce qui s’est produit lorsque le vrai fournisseur a appelé. Lorsqu’une autorisation Stripe revient avec webhook_timeout, vous devez répondre à une question : la requête est-elle parvenue jusqu’à ma machine et que fait votre gestionnaire avec elle ?
InstaTunnel’s CLI documents an --logs flag that polls live request logs, and states that request logs require the Pro or Business plan. That gives you a record of requests that crossed the tunnel, which you can set against your handler’s own logs and against Stripe’s request_history for the same authorization. A practical workflow:
- Find the authorization in Stripe and note its
request_history.reasonandreason_message. - Find the matching request in the tunnel’s request logs. If it is missing, the problem is upstream of your laptop. If it is present, the problem is in or after your handler.
- Match it to your handler’s structured log line and its
handler_msvalue.
Keep your handler’s own duration log as the source of truth either way, since a tunnel’s log view is a record of traffic and not a substitute for timing your own code.
On the Shopify side, the Dev Dashboard’s Logs page lists individual deliveries from the past 7 days, filterable by topic, status and shop. Shopify notes that this view is not real time and data can lag by up to several minutes, so do not conclude a delivery is missing right after it fails.
Maintenir un gestionnaire sur portable rapide
Un ordinateur portable est un bon endroit pour construire un gestionnaire synchrone et un endroit impitoyable pour en faire fonctionner un si vous ignorez ses habitudes. Voici les façons les plus courantes dont les gestionnaires locaux perdent leur budget.
Éliminer les chemins à froid
La première requête après une période d’inactivité est souvent la plus lente. Les pools de connexions sont vides, les caches sont froids, et l’exécution du langage peut encore se réchauffer. Avant un test, envoyez quelques requêtes de débogage. Pendant le test, maintenez vivants les clients de base de données et HTTP et réutilisez les connexions au lieu d’en ouvrir une nouvelle à chaque requête.
Décidez en mémoire
Pour Stripe Issuing, concevez la décision de façon à n’avoir besoin d’aucun aller-retour réseau. Chargez vos règles de dépenses, vos listes blanches de catégories de marchands et vos limites par carte en mémoire au démarrage et rafraîchissez-les selon une minuterie. La charge utile d’autorisation porte déjà les détails du marchand et les métadonnées attachées à la carte, et la documentation des agents Stripe suggère des vérifications courantes telles que l’appariement du commerce à la tâche de l’agent, la vérification du montant par rapport au budget prévu et le signalement d’une vitesse de transaction inhabituelle. Tout cela peut être exécuté sur des données en mémoire. Une décision qui lit quelques cartes mémoires prend des microsecondes. Une décision qui attend une base de données distante est un ticket de loterie face à l’horloge.
Si votre plate-forme d’agent souhaite un modèle pour juger un achat, effectuez cette analyse à l’avance et mettez le verdict en cache, ou faites en sorte que le modèle règle les contrôles de la carte à l’avance. La documentation de Stripe indique que les limites de dépenses et les contrôles par catégorie de marchands sont définis lors de la création de la carte et peuvent être mis à jour à tout moment. Un appel de modèle dans la fenêtre de deux secondes est l’endroit le plus coûteux pour placer votre jugement que vous auriez pu encoder plus tôt.
Mettez chaque appel sortant derrière un délai
Envelopperez tout ce qui peut bloquer dans un délai, et rendez la décision de repli explicite :
const controller = new AbortController();
const timer = setTimeout(() =\u003e controller.abort(), 400);
try {
const risk = await fetch(RISK_URL, { signal: controller.signal });
// utiliser le résultat
} catch {
// délai dépassé : appliquez votre politique par défaut documentée
} finally {
clearTimeout(timer);
}
Choisissez délibérément le défaut. Refuser protège les dépenses mais frustre un achat légitime. Approbation maintient les agents en flux mais élargit l’exposition. Quelle que soit votre choix, écrivez-le, car Stripe appliquera autrement vos paramètres de délai.
Maîtriser la machine
- Alimentation et veille. Un ordinateur portable sur batterie peut limiter le CPU, et un portable en veille ne répond pas. Restez branché et gardez la machine éveillée lors des tests.
- Jitter du Wi‑Fi. Les liens sans fil ajoutent une latence variable que la médiane masque et que le p99 révèle. Testez au moins une fois sur Ethernet pour voir quelle part est due à votre radio.
- Charge en arrière-plan. Une compilation locale, un conteneur qui tire des images, ou un client de synchronisation peut voler du CPU exactement au moment où une requête arrive. Vérifiez ce qui tourne avant de faire confiance à un mauvais chiffre.
- Mode débogage. Un débogueur suspendu sur un point d’arrêt détruira tout budget. Utilisez les journaux, pas les points d’arrêt, pour les tests de latence.
Accusez réception en premier lorsque le fournisseur le permet
Pour Shopify, renvoyez 200 au moment où la charge utile est reçue et vérifiée, puis mettez le véritable travail en file d’attente. Persistez l’événement brut dans une file locale ou un fichier avant de répondre, afin qu’un plantage après l’accusé de réception ne perde pas de données. Comme les essais signifient que le même événement peut arriver plus d’une fois, rendez le traitement en aval idempotent. Le page Shopify « Vérifier les livraisons » couvre la vérification HMAC et la gestion des livraisons en double. Si votre application est hors ligne pendant une longue période, la recommandation de Shopify est de vous réabonner là où nécessaire et de réimporter les données manquantes.
Liste de vérification pré-vol
Passez ceci en revue avant d’enregistrer une URL de tunnel auprès d’un fournisseur pour des événements synchrones :
- Connaître la fenêtre : 2 secondes pour les autorisations en temps réel de Stripe Issuing, 5 secondes pour les webhooks Shopify.
- Définissez un délai interne bien en deçà de la fenêtre.
- Mesurez le temps du gestionnaire, puis le temps total à travers le tunnel, aux p50, p95 et p99.
- Chauffez le gestionnaire et réutilisez les connexions.
- Gardez les données de décision en mémoire.
- Donnez à chaque appel sortant un délai d’expiration strict et une stratégie de repli explicite.
- Pour Stripe, retournez la décision directement avec un en-tête
Stripe-Versionvalide, vérifiez les signatures, et surveillezrequest_history.reasonpourwebhook_erroretwebhook_timeout. - Pour Shopify, accuser réception en premier, mettre le travail en file d’attente, et surveiller le temps de réponse p90 et le taux d’échec du Dev Dashboard.
- Gardez l’URL du tunnel stable entre les exécutions afin de l’enregistrer une seule fois.
- Passez en revue les journaux de requêtes après chaque échec.
Tests sans attendre une vraie carte
Vous n’avez pas besoin d’une carte physique pour tester le chemin. Stripe fournit des aides de test Issuing, y compris une API Authorization Create qui simule une nouvelle autorisation sur une carte Issuing. Il existe des aides correspondantes pour les autorisations incrémentales et les rétrogradations. Configurez votre point d’autorisation en temps réel dans les paramètres Issuing avec l’URL de votre tunnel, créez des autorisations via l’aide et observez ce qui arrive. Exécutez-le par lots afin de voir le comportement en queue et non une seule requête chanceuse.
Les documents Stripe décrivent également une boucle locale plus légère. stripe listen --forward-to localhost:4242/webhook transmet les événements à votre serveur, et stripe trigger issuing_authorization.request déclenche un événement de test à partir du CLI. C’est pratique pour vérifier votre logique. Pour mesurer la latence du tunnel, envoyez le trafic par le tunnel lui-même.
Pour Shopify, le Dev Dashboard vous permet de déclencher une livraison en mettant à jour votre boutique de développement, par exemple en créant un produit pour déclencher products/create, puis lire le temps de réponse de la livraison.
La takeaway
Les webhooks synchrones transforment la latence en exigence de correction. Stripe vous donne 2 secondes pour produire une décision. Shopify vous donne 5 secondes pour produire un accusé de réception. Aucune des deux fenêtres n’est généreuse une fois que vous ajoutez Internet, un tunnel et un ordinateur portable qui exécute aussi votre éditeur.
La bonne nouvelle est que le budget est facile à gérer une fois que vous cessez de deviner. Mesurez votre gestionnaire, mesurez le chemin complet, regardez la queue, conservez les décisions en mémoire, mettez des échéances sur chaque appel sortant, et lisez les journaux de requêtes lorsque quelque chose manque. Faites cela et le tunnel devient une seule ligne d’inventaire petite et connue plutôt que le suspect dans chaque timeout.
Sources
- Stripe: Autorisations en temps réel (Issuing)
- Stripe: Autorisations Issuing
- Stripe: Issuing for agents
- Stripe: Pay with a Shared Payment Token from an Issuing card
- Shopify: Dépanner les webhooks
- InstaTunnel: CLI README
Related InstaTunnel pages
Continue from this article into the most relevant product guides and workflows.
Related Topics
Keep building with InstaTunnel
Read the docs for implementation details or compare plans before you ship.