Migrating your webhooks
Moving delivery is not a flag day. These are the four patterns, from the safest to the simplest, and how to choose between them.
In short
- Consumers that verify Standard Webhooks signatures usually need no change at all.
- Run both systems in parallel first: publish to each and compare, before anything is switched.
- Move tenant by tenant, not all at once — the blast radius of a mistake is then one customer.
- Keep the old system able to receive for a while. A migration you cannot reverse is a gamble.
The four patterns
| Pattern | How it works | When to choose it |
|---|---|---|
| Shadow | Publish to both systems; the old one still delivers, ours only records | High volume, or a consumer base you cannot afford to disturb |
| Dual delivery | Both systems deliver; consumers dedupe on the delivery id | Consumers already deduplicate and you want real proof under load |
| Per tenant | Switch customers in batches, oldest and smallest first | The default. Blast radius is one batch |
| Cut over | Change the publisher and stop the old system | Small consumer counts, or a homegrown system you control entirely |
Whatever the pattern, do this first. Point one test destination at a service you control, publish a handful of events, and verify a signature end to end. Two hours of that removes most of the risk in the rest of the plan.