待機するウェブフック: 同期イベントの遅延予算
Stripe は 2 秒、Shopify は 5 秒を許容します。トンネルホップの遅延を測定し、ウェブフック遅延予算を作成し、ローカルハンドラを高速に保つ方法。

Quick answer
ウェブフック遅延予算: Stripe 2秒、Shopify 5秒: 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.
ほとんどのウェブフックは礼儀正しいです。プロバイダーがイベントを送信し、あなたのサーバーが「了解しました」と返答し、残りは後で行われます。とはいえ、礼を欠くウェブフックもあります。実際の取引を止め、あなたを待たせます。
そのハンドラをトンネルの奥にあるノートパソコン上で開発している場合、新たな問題が生じます。時計はすでに動いており、トンネルのホップはその一部にすぎません。本ガイドでは現在の予算が何であるか、各予算のどれくらいがあなたのトンネルで消費されているかを測る方法、そしてあなたのローカルハンドラを十分高速に保ち、運だよりでなくロジックを検証できる状態にする方法を解説します。
現時点で重要な2つの予算
Stripe Issuing: 2 秒、そして答えは決定
Stripe Issuing を通じて発行されたカードが使用されると、Stripe は Issuing 残高に十分な資金があること、カードが有効であること、そして購入を許可する設定が適用されていることを確認します。これらの検証をクリアしたうえでリアルタイム認証ウェブフックを設定している場合、Stripe はエンドポイントへ issuing_authorization.request イベントを送信します。2 秒以内に承認または却下を行わない場合、タイムアウト設定(ダッシュボードの Issuing 設定)または Autopilot 設定が有効になっていれば、それに従って Stripe が自動的に承認または却下を行います。
四つのポイントが現在のドキュメントからこの設計を形作ります:
- 「返答そのものが決定です。」 ウェブフックに直接
200ステータスと JSON 本文で応答します。approvedフィールドは必須です。レスポンスにはStripe-Versionヘッダーも必須で、受け付けられるコンテンツタイプはapplication/jsonのみです。 - 「失敗には名前がある。」 認証の
request_history.reasonがwebhook_errorまたはwebhook_timeoutの場合、Stripe はあなたの応答を受け取っていません。webhook_errorはリクエストヘッダー内の Stripe API バージョンが無効であるか、Stripe があなたの応答を処理できなかったことを意味します。webhook_timeoutは他のすべての失敗モードを含みます。 Stripe は統合の健全性を判断するためにapprovedフラグを使うべきではないと警告します。 なぜならエラー時には Autopilot が代わりに承認することがあるからです。 調査すべき例として、approved: trueでありながらrequest_history.reason: webhook_errorの認証があります。 これらを監視するにはissuing_authorization.createdおよびissuing_authorization.updatedを購読し、詳細なエラーテキストはrequest_history.reason_messageを読んでください。 - 「フォールバックは存在するが、それはあなたのロジックではない。」 現在公開プレビュー中の Autopilot は、システムがダウンしている、応答しない、または無効な応答を返した場合に、事前定義されたルールセットからあなたに代わって意思決定を行います。設定は Stripe サポートへの連絡で行います。独自の専用 BIN を持つユーザー向けの別の Stripe Autopilot も公開プレビュー中で、カードネットワークが Stripe に接続できない場合に役立ちます。これらの決定には
network_fallbackのラベルが付けられます。どちらもタイムリーな応答の代替にはなりません。 - 「すべての購入があなたの元に届くわけではない。」 認証リクエストのみが同期エンドポイントへ送られます。他の通知は通常の webhook エンドポイントへ送られます。Issuing の残高が不足している場合、認証は拒否され、Webhook はリクエストを受け取りません。支出コントロールの拒否は Stripe 側でも発生します。リアルタイムの webhook が設定されていない場合、Stripe は自身の検証を通過した認証をリクエストを送らずに承認します。
なぜこれが急にみんなの問題になったのか
Stripe の Issuing for agents のドキュメントは、各エージェントに対してエージェントごとの支出上限、商業カテゴリの制御、カスタム認証ルールを備えた仮想カードを割り当てることを説明しています。また、カードをエージェントに渡すと、支払いが完了する前にすべての購入試行がリアルタイムの認証リクエストを引き起こすことも記載されています。同じページには、Stripe がカードのデフォルトルールに戻る前のデフォルトの応答タイムアウトが2秒とある、とも記載されています。
プログラム的チェックアウトのガイドは別の経路を追加します。販売者が Issuing カードで資金提供された Shared Payment Token (SPT) を償還すると、支払いはキャプチャと清算の前に、既存の Issuing のリアルタイム認証経路を通過します。そのガイドでは、Issuing カードから PaymentMethod を作成するにはプライベートプレビューアクセスが必要で、SPT リクエストはプレビュ API バージョン 2026-04-22.preview を使用します。このフローを、構築前に現在のドキュメントと照合するものとして扱ってください。
換言すれば、エージェントが何かを購入することは、現在では通常の issuing_authorization.request イベントのソースとなっており、すべてが2秒の時計を意味します。
Shopify: 5 秒、そして返答は確認応答
Shopify のウェブフックのトラブルシューティングドキュメントは、アプリが5秒以内に応答する必要があること、200 系ステータスが成功として数えられることを示しています。遅いハンドラに関するガイダンスは、レスポンスを送信した後で処理を遅らせることです。
- Shopify は、失敗した配信を最大8回、4時間の間隔で再試行します。各再試行の間隔は増加します。
- 失敗が続く場合、購読は削除されます。削除された購読には何も受け取れません。再作成するまで待つ必要があります。
- Dev Dashboard はあなたの90パーセンタイルの応答時間と失敗した配信率を表示します。0.5%を超える失敗率は「平均より高い」と説明されます。4〜5秒の応答時間はリミットに危険に近いとフラグされます。
Stripe issuing_authorization.request |
Shopify ウェブフック | |
|---|---|---|
| ウィンドウ | 2 秒 | 5 秒 |
| 返す内容 | 決定そのもの | 2xx の確認応答 |
| 応答後の処理 | 決定には不可 | 想定され、推奨 |
| ミス時 | タイムアウト設定(または Autopilot)で決定 | 最大8回リトライ、その後購読削除 |
Shopify で clock を誤魔化すことは、速く返答して後で処理することで可能ですが、Stripe Issuing ではできません。後で行う作業は Stripe が待っているからです。
2,000 ms 予算の解剖
ウィンドウを、使い切る予算として捉えます。同期ウェブフックの場合、Stripe がリクエストを送信してから応答を受け取るまでの時間は、次のように概算されます:
- Stripe からトンネルのエッジへ(インターネット伝送、TLS)
- トンネルのエッジからマシン上のトンネルエージェントへ(トンネル自体)
- エージェントからローカルサーバーへ(ループバック、ほぼ無料)
- あなたのハンドラ(解析、検証、意思決定ロジック、I/O)
- 同じ経路で外へ戻る
以下は、計画値の割り当て例です。これらはサービスの測定値ではありません:
| セグメント | 計画上の許容量 |
|---|---|
| 受信ネットワークと TLS | 100–300 ms |
| トンネルホップ、往復 | 50–200 ms |
| 署名検証と解析 | 10 ms 未満 |
| 決定ロジック | 100 ms 未満 |
| 安全マージン | 800 ms 以上 |
表が示す意味に注意してください。ハンドラが1回の DB クエリや1回の外部 API コールを実行しただけで、余白を使い切っても気づかないことがあります。測定こそが答えです。
有用なルールは、提供元のウィンドウよりかなり短い内部締切を設定することです。例えば Stripe では 800–1,000 ms を目安にし、それまでにハンドラが最良の回答を返すようにします。自分でタイムアウトを決めた場合、フォールバックの決定を選択します。Stripe の時計が決定すれば、ダッシュボードの設定(または Autopilot)がそれを選択します。
トンネルホップの測定
測定していないものは引けません。3つの測定を行い、それらを比較してください。
1. ハンドラ自体の計測
自分のコードを計器化します。これがトンネルが影響できない数値です。以下は、標準の Server-Timing ヘッダで自身の所要時間を報告する、最小限の Node/Express の例です:
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. Verify the Stripe-Signature header against req.body (the raw bytes),
// for example with stripe.webhooks.constructEvent().
// 2. Run your decision logic.
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"); // use a supported version, see Stripe's API versioning docs
res.set("Server-Timing", `handler;dur=${ms.toFixed(1)}`);
res.json(decision);
});
app.listen(3000);
The Stripe-Version value above is the one used in Stripe’s own example. Check Stripe’s API versioning page for supported values, because an invalid version header is a documented cause of webhook_error. Stripe’s docs also say to verify webhook signatures and allowlist Stripe’s IP addresses so you only act on genuine Stripe events.
2. curl でリクエストの端から端を計測
curl はリクエストを段階に分けることができます。各値はリクエスト開始からの累積タイムスタンプです:
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'
同じコマンドを http://localhost:3000/stripe/issuing に対して実行します。複数回の実行から得られる total の差は、あなたの位置から見たトンネルのオーバーヘッドです。署名を検証するハンドラの場合、署名のないテストリクエストは早い段階で拒否されます。テストの回避策を追加するか、正しく署名されたペイロードを送ってください。
3. 中央値ではなくパーセンタイルを比較
予算は遅い尾部で崩れるので、平均ではなく p50、p95、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)]}'
実測がもたらす補足
ライブラリのテストや検証の際には、実環境をできるだけ再現するため、トンネルの外側と内側の両方で測定を取ることが有効です。詳細なワークフローは本文をご参照ください。
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.