The Event That Broke Your App Three Days Ago Is Still There

Your webhook handler has been silently failing on a specific event type for three days. You noticed it today when a customer called in. The symptoms point to a webhook issue — a field your handler expected was present in the documentation but absent in the actual payload — but the events are gone. You checked your log rotation settings: your application logs rotate every 48 hours. You checked ngrok: your last tunnel session ended on Tuesday. You checked Webhook.site: the link expired.

The event exists. Stripe has a record of sending it. But you have no copy to inspect.

You ask Stripe support to resend the event. They will, but only the most recent instance. The specific event from three days ago — the one whose payload you need to see to understand the schema change — is gone.

This is the hidden cost of session-scoped and short-retention webhook tools: they are useful while you are actively debugging, and useless when you are debugging something that happened in the past. Most webhook bugs are discovered in the past. A customer reports an issue today. The issue started three days ago. You need the events from three days ago.

HookTunnel stores every event. The Free tier gives you 24 hours. The Pro tier gives you 30 days. The Team tier gives you 90 days. The Enterprise tier gives you 1 year. The event from three days ago is there. So is the one from three weeks ago, if you are on Pro.

Why retention length matters more than it seems

The monthly billing cycle

Subscription billing webhooks from Stripe arrive on a monthly cycle. customer.subscription.updated, invoice.finalized, invoice.paid. If your billing handler has a bug that only manifests in certain edge cases — plan upgrades that happen on the same day as a renewal, or prorated charges for mid-cycle changes — that bug may only produce a failing event once a month, in a specific scenario.

To debug it, you need the event from when it happened. With 24-hour retention, the event from last month's billing cycle is gone the day after it arrived. With 30-day retention, you have it. You can inspect it, replay it in a test environment, compare it to the events from a successful billing cycle, and identify the schema difference that causes the bug.

Quarterly finance reconciliation

If your business uses webhooks to trigger revenue recognition events — Stripe payment confirmations, billing system updates, subscription activation signals — your finance team needs to reconcile these events quarterly. They need to answer: "Which payment events came in this quarter? Which ones were applied? Are there any gaps?"

With 90-day retention on the Team plan, your finance team can query the full quarter's webhook history, filter by event type, and see the delivery and application status for every payment event. The reconciliation becomes a dashboard query, not a manual spreadsheet exercise.

Annual audit trails

Enterprise companies under SOC2, ISO 27001, or financial regulations often need to demonstrate that specific events were processed correctly during an audit period. "Show me every payment webhook you received in Q3, with proof of delivery and application" is an audit question that requires a full year of retention to answer reliably.

The Enterprise tier's 1-year retention makes the webhook history an audit artifact, not just a debugging aid.

How retention filtering works

Retention limits are applied at query time, not at write time. Events older than your tier's retention limit are not automatically deleted on a rolling basis — they are filtered from your view and from API responses.

This has a practical implication: if you upgrade your plan, you do not lose access to events that were captured under a lower-tier retention limit but still exist in the database. If you were on Free for the last month and upgrade to Pro, you gain access to any events from the last 30 days that HookTunnel captured while you were on Free, up to the 30-day Pro limit.

Downgrading works the other way: if you move from Pro to Free, your retention view drops to 24 hours. Events from day 2 through day 30 are filtered from your view. If you re-upgrade, they become accessible again (as long as they are within the new tier's retention window and have not been permanently deleted by a data deletion request).

The upgrade nudge

When you are viewing your event list and older events exist that are gated by your current tier, HookTunnel shows a banner at the point in the list where older events begin:

"Events from 3 days ago and earlier are available on Pro. Upgrade to access 30 days of history."

The older events are counted (you can see how many exist), but their payloads and metadata are not displayed. This is intentional: you know the events are there, you know how many there are, and you know exactly what upgrading would give you access to.

Search across history

The full retention window is searchable with HookTunnel's semantic search. If you remember that a customer had a payment issue "sometime last month" but do not know the exact date, you can search by description — "payment failed for enterprise customer" — and semantic search returns matching events from within your retention window, even if those exact words do not appear in the payload.

For time-bounded searches, the event list lets you filter by arbitrary date ranges within your retention window. "Show me all Stripe events from November 14 to November 16" is a three-click operation.

Replay from history

Every event in your retention history can be replayed. An event from 25 days ago (within your Pro retention window) can be re-sent to your current handler URL with one click, or queued for batch replay.

This makes retention a recovery tool, not just a debugging aid. If your handler was broken for a week and you fixed it today, your entire retention history is available for replay. You are not limited to replaying only the last 24 hours of events; you can recover from the full window of the outage.

Replay of events with different storage modes: events stored in raw_encrypted mode replay with the exact original payload. Events stored in redacted mode replay with the redacted payload (PII fields contain [REDACTED]). Events stored in none mode cannot be replayed — the payload was not stored.

The engineer who found a bug from three weeks ago

Priya is an engineer at a SaaS company on HookTunnel's Pro plan. A customer reports that they were not notified when their subscription renewed — they expected an email confirmation that never arrived. The customer says the renewal happened on the 3rd of the month, about 22 days ago.

Without 30-day retention: Priya has nothing to inspect. She knows the event arrived (Stripe has a record), but she cannot see the payload, the delivery status, or whether her handler processed it correctly. She must ask Stripe to resend a test event and debug against that — which may not reproduce the exact payload from 22 days ago.

With 30-day retention: Priya opens HookTunnel, filters to customer.subscription.updated events from around the 3rd. Finds the event. The event detail shows: HTTP 200, handler latency 48ms, delivery successful. The event was delivered. She checks the outcome receipt status: Applied Unknown. No receipt arrived — her handler returned 200 but never sent a confirmation.

She reads the event payload. The metadata.notification_preference field on this customer's subscription is set to "none". Her handler has a bug: it sends the notification email before checking the notification preference. But the notification service returns 200 even when it sends nothing (because "sending nothing" is a valid operation). Her handler has no way to know the email was suppressed.

The receipt would have caught this if it were implemented — a receipt confirming the side-effect (email sent) would never have arrived, and the event would have shown up in the reconciliation gap view. But even without receipts, the 22-day-old event payload is there, inspectable, and it contains the exact information needed to diagnose the bug.

Priya files a bug: handler does not respect notification_preference: none. She replays the 22-day-old event (in a test environment pointed at a staging handler) with the bug fixed to verify. The test passes. She deploys the fix.

None of this was possible without 30-day retention.

Comparison with alternatives

| Tool | Free Retention | Paid Retention | Session-Scoped | |---|---|---|---| | HookTunnel | 24 hours | 30d / 90d / 1yr | No | | ngrok | None (inspect only) | Session-scoped only | Yes | | Webhook.site | 7 days | 7 days (no upgrade) | No | | RequestBin | Limited | Not publicly documented | No | | Stripe Dashboard (own events) | ~30 days (read-only) | ~30 days (read-only) | N/A |

The Stripe Dashboard gives you ~30 days of Stripe event history, but it is read-only and Stripe-specific. You cannot search semantically, replay freely, or attach events to investigations. And it only covers Stripe — for Twilio, GitHub, or your own internal webhooks, there is no equivalent built-in history tool.

HookTunnel's retention is provider-agnostic. Every webhook, from every provider, stored with the same retention policies and the same debugging capabilities.

Frequently asked questions

What happens to my events when I downgrade from Pro to Free?

Events from day 2 onward become inaccessible in your event list and API responses. They are filtered, not deleted. If you re-upgrade to Pro within 30 days of those events being captured, they become accessible again. After 30 days from capture, they are permanently deleted per HookTunnel's data lifecycle policy.

Can I export my full history before downgrading?

Yes. From the event list, you can export all events within your current retention window to CSV or JSON. We recommend exporting before downgrading if you need a permanent record beyond the Free tier's 24-hour window.

Is there a per-event size limit that affects retention?

Payloads up to 5MB are stored in full. Payloads larger than 5MB are stored with metadata only (headers, timestamp, delivery status) and the body truncated at 5MB. The truncation is noted in the event detail view.

Does the retention window start when the event arrives or when I create my account?

The retention window starts from event arrival. If you create a Pro account today and an event arrived 15 days ago — but that event was captured by HookTunnel because your hook already existed — that event is within your 30-day Pro retention window.

Can I set different retention periods for different hooks?

Retention is tier-based, not hook-based. All hooks in your account share the same retention limit based on your plan. Per-hook retention configuration is available on Enterprise plans as a custom arrangement.

How do I access events approaching the end of their retention window?

The event list shows all events within your retention window, sorted by most recent by default. Events are not flagged as "expiring soon" — if you need to preserve specific events beyond your retention limit, export them before they expire.