How to Migrate From In-House Webhooks to a Delivery Platform in Two Weeks

The reason teams stay on in-house webhook systems long after they should is not sunk cost, it is migration fear. A bad cutover breaks payment notifications for your biggest customer at 2am on a Saturday. That is a career event, and everyone knows it.

The safe migration is boring on purpose. Two weeks, dual-write, customer-by-customer promotion, single-flag rollback. Nobody notices except your on-call, who gets a quieter month once it lands.

What are the preconditions before you start?

Do not begin a migration without these five in place.

• A complete list of active endpoints. Every subscription, every URL, every signing secret. Extract from your current system's database.
• A canonical event schema. The exact JSON shape you currently send, per event type. If schemas have drifted over time, freeze the current shape as the reference.
• A retry policy match. The new platform must be configured to match your current retry ladder within tolerance. Different backoff curves can surprise customers even if the delivery contract is otherwise unchanged.
• Access to the new platform's API keys and dashboards. Not blocked on procurement or provisioning.
• A rollback runbook. Written, reviewed, and rehearsed once with a dry-run on a test customer before the real migration starts.

If any of these is missing, the two-week plan slips to four weeks. That is fine. Do not skip the preconditions to fit a calendar.

What is the week-one integration plan?

Five workdays, all internal, no customer impact.

Shadow mode is the critical hour. Customers receive from both systems, but their receivers dedupe on the event id you already ship in the payload. If your receiver does not dedupe, add a header the customer can ignore, so the new system's events are visually distinguishable but functionally identical in the receiver.

How do you set up dual-write correctly?

Two rules that non-obviously prevent problems.

• The dual-write happens in your emitter, not in either webhook system. Both systems get called from the same code path with the same event body. That way schema divergence is impossible.
• The event id is the same across both systems. If your old system generates event ids and the new one does too, override the new system to accept your existing id. Dedup at the receiver depends on this.

Do not attempt "dual-write" by having the old system forward to the new one. That couples the two systems and defeats the point. Both must be independently reachable from your emitter, both must fail independently, both must be measurable independently.

What is the week-two promotion sequence?

Ten workdays or fewer. Customers move from "receives from old system" to "receives from new system" one at a time, smallest first.

• Mon. Promote the three smallest customers to new system as primary. Old system continues in shadow mode. Watch tickets and metrics for 24 hours.
• Tue. Promote the next ten customers, still by volume ascending. Continue watching metrics.
• Wed to Thu. Batch promote 50% of remaining customers in tranches of 20, spaced two hours apart. If any tranche triggers a rollback criterion, halt and investigate.
• Fri. Promote all remaining customers except your top five.
• Following Mon to Wed. Promote the top five one per day, so if the biggest customer breaks you find out before you touch the next-biggest.
• Following Thu. Disable dual-write. Old system is now cold.
• Following Fri. Decommission old system code paths, leaving the emitter path clean.

Never promote by event type. Promote by customer. A partial migration where "invoice.paid goes through new but subscription.updated goes through old" is a two-system consistency problem you will not enjoy debugging.

How do you handle in-flight retries at cutover?

An event that is mid-retry on the old system when you promote its customer has three possible fates. Only one is acceptable.

• Bad. Old system completes the retry, new system never sees it, customer's system has the event with the old signing key and stale delivery metadata.
• Bad. Old system gives up, new system re-emits, customer gets a duplicate.
• Good. Old system completes the retry with the old signing key, new system detects the successful ack, marks it delivered, does not re-emit.

The good path requires the emitter to reconcile after cutover. On promotion, the old system stops accepting new events for that customer but continues retrying in-flight ones. On success, it emits a "delivered" signal the new system consumes. On failure past the retry ladder, the new system generates a fresh delivery attempt with a new event id.

Practically, most emitters cannot express this cleanly. The workaround is a two-hour freeze window per customer: no new events emitted, retries drain on the old system, then the new system takes over. Two hours of latency for events emitted during the window is acceptable if the customer is warned.

What are the specific rollback triggers?

Rollback is single-flag: flip the customer back to the old system as primary. Dual-write stays on. Investigate later.

• Success rate degrades. New system's rolling one-hour success rate is more than 0.1% below the old system's rolling one-hour baseline for that customer.
• Latency degrades. Median delivery latency increases by more than 500ms or p99 increases by more than 2 seconds.
• Support signal. Three customers report webhook issues within a 24 hour window, unless the reports clearly trace to endpoint-side outages.
• Signature failures. More than five signature verification failures per hour, across any customer.

Any single trigger fires rollback. Do not debate. Roll back, then debug from the rolled-back state. This is the entire point of dual-write.

What do you communicate to customers?

Nothing during the migration, if you can help it. The best migration is invisible.

If you have contractual obligations to notify (some enterprise contracts require change notice for infrastructure), send a status update seven days ahead framed as "operational improvement to our webhook delivery system. No changes required on your side." Do not name the vendor. Do not describe the internal architecture change.

After the migration, if anything, announce the new customer-facing capabilities the new platform enables: a debug dashboard, payload search, longer retention. Those are the things customers actually care about.

What actually matters

The mistake to avoid is treating this as a version-cut migration where you switch at a moment in time. It is a gradual promotion, per customer, with dual-write as the safety net and single-flag rollback as the escape hatch. Teams who lose customers on webhook migrations always lose them because they promoted too fast, batched too many customers, or turned off the old system before they were sure of the new one. Two weeks is the fast version of the safe path. Six weeks is the safe version of the safe path. Never do the fast version of the fast path.