InstaTunnel
Basculer le menu de navigation
API
14 min read
61 views

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.

IT
InstaTunnel Team
Published by the InstaTunnel team | Editorial policy
Webhooks qui attendent : budgets de latence pour les événements synchrones

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 200 et un corps JSON. Le champ approved est requis. L’en-tête Stripe-Version est également requis sur la réponse, et application/json est le seul type de contenu accepté.
  • L’échec a un nom. Lorsque la request_history.reason d’une autorisation est webhook_error ou webhook_timeout, Stripe ne reçoit pas vos réponses. webhook_error signifie 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_timeout couvre tous les autres modes d’échec. Stripe avertit également de ne pas utiliser le drapeau approved pour 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 avec approved: true mais request_history.reason: webhook_error. Abonnez-vous à issuing_authorization.created et issuing_authorization.updated pour surveiller ces cas, et lisez request_history.reason_message pour 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 :

  1. De Stripe jusqu’au bord du tunnel (transit Internet, TLS)
  2. Du bord du tunnel à l’agent du tunnel sur votre machine (le tunnel lui-même)
  3. De l’agent à votre serveur local (loopback, essentiellement gratuit)
  4. Votre gestionnaire (analyse, vérification, logique de décision, entrées/sorties)
  5. 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 curl depuis 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:

  1. Find the authorization in Stripe and note its request_history.reason and reason_message.
  2. 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.
  3. Match it to your handler’s structured log line and its handler_ms value.

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 :

  1. Connaître la fenêtre : 2 secondes pour les autorisations en temps réel de Stripe Issuing, 5 secondes pour les webhooks Shopify.
  2. Définissez un délai interne bien en deçà de la fenêtre.
  3. Mesurez le temps du gestionnaire, puis le temps total à travers le tunnel, aux p50, p95 et p99.
  4. Chauffez le gestionnaire et réutilisez les connexions.
  5. Gardez les données de décision en mémoire.
  6. Donnez à chaque appel sortant un délai d’expiration strict et une stratégie de repli explicite.
  7. Pour Stripe, retournez la décision directement avec un en-tête Stripe-Version valide, vérifiez les signatures, et surveillez request_history.reason pour webhook_error et webhook_timeout.
  8. 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.
  9. Gardez l’URL du tunnel stable entre les exécutions afin de l’enregistrer une seule fois.
  10. 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

Continue from this article into the most relevant product guides and workflows.

Related Topics

#webhook latency budget#synchronous webhooks#webhook timeout#webhook response time#webhook latency#webhook performance#webhook best practices#webhook debugging#webhook testing locally#localhost webhooks#local webhook development#webhook tunnel#tunnel latency#ngrok alternative#localhost tunneling#expose localhost#localhost tunnel#InstaTunnel#tunnel request logs#request inspection#webhook request logs#Stripe webhooks#Stripe issuing authorization#issuing_authorization.request#Stripe real-time authorizations#Stripe 2 second timeout#Stripe agent purchases#Stripe webhook timeout#Shopify webhooks#Shopify webhook timeout#Shopify 5 second response#Shopify webhook troubleshooting#real-time authorization#synchronous event handling#synchronous vs asynchronous webhooks#event-driven architecture#latency budget#latency budgeting#p99 latency#tail latency#round trip time#API latency#low latency API#API response time#handler performance#cold start latency#webhook retries#webhook reliability#webhook idempotency#webhook signature verification#payment webhooks#fintech webhooks#developer tools#developer infrastructure#DevOps#backend development#API development#cloud-native#networking#performance optimization

Keep building with InstaTunnel

Read the docs for implementation details or compare plans before you ship.

Share this article

More InstaTunnel Insights

Discover more tutorials, tips, and updates to help you build better with localhost tunneling.

Browse All Articles