Turning on the second header takes one variable
On September 21, 2026, Hookdeck shipped compat signatures in Outpost v1.4.0, its open-source outbound webhook server. Set DESTINATIONS_WEBHOOK_COMPAT_SIGNATURE_HEADER_NAME and every delivery carries a second signature in your previous format next to the primary one. Companion DESTINATIONS_WEBHOOK_COMPAT_* settings describe the old content template, encoding and algorithm. Both signatures use the same destination secret, so receivers keep their credentials. Leave the header name unset and nothing changes. It also works in Standard Webhooks mode.
This is the right feature. If you are moving senders from a homegrown HMAC header to Standard Webhooks, dual-signing is the only migration that doesn't hand every customer a deadline. Immuta did the same thing earlier this year. It added x-immuta-webhook-signature-sha256 next to the HMAC-SHA1 x-immuta-webhook-signature, made it opt-in on January 20, the default on March 16 and mandatory on April 16, 2026.
The part nobody ships a setting for is the end. At some point you have to stop sending the old header. And from the sender's side you have almost no information about who will break when you do.
A 2xx tells you nothing about which header was checked
A receiver that verifies the new header, one that verifies the old header, one that accepts either, and one that verifies nothing at all all return the same 200. Your delivery logs look identical for all four.
You can count adoption of your SDK version. You can count customers who clicked "I've updated my integration" in the dashboard. Neither tells you what code is running behind the endpoint. SDK versions say nothing about hand-rolled verifiers, and dashboard checkboxes get clicked by people who haven't deployed yet.
So most senders do what Immuta did. They pick a date, announce it, and accept that some receivers will start returning 401 on that date. That works when you have a few hundred enterprise customers and a support team. It works badly when you have forty thousand endpoints, a third of them owned by people who left the company.
You can do better than a date. But first, two things that make the dual-signing period itself trickier than it looks.
Same secret, two different keys
"Same secret" is true at the string level and often false at the byte level. Standard Webhooks secrets look like whsec_ followed by base64, and the spec says to strip the prefix and base64-decode the rest to get the HMAC key. Plenty of legacy schemes feed the whole secret string to HMAC as UTF-8 bytes. Same string in your database, two different keys.
Get this wrong in the compat path and the legacy header is invalid on every delivery. Receivers who haven't migrated start failing the moment you turn on the feature that was supposed to protect them. Polar ran into a version of this from the receiving side, where one whsec_ secret mapped to two schemes depending on when it was created. We covered that in /blog/webhook-secret-regeneration-signing-scheme.
The fix is boring: a fixture test that signs a known body with a known secret through the compat path and compares it against a signature your old production code produced. Your new code's idea of the old format is exactly what you are testing, so it can't be the reference.
Sign both headers inside the delivery loop
Compute both signatures on every attempt. If your new scheme carries a timestamp, a signature frozen before the first attempt is already stale by the third retry. That bug has its own post at /blog/webhook-signature-timestamp-retry-tolerance. Dual-signing doubles the places to get it wrong.
import { createHmac } from 'node:crypto'
type LegacyMode = 'send' | 'omit'
function signAttempt(
secret: string,
msgId: string,
body: string,
legacy: LegacyMode
): Record<string, string> {
const ts = Math.floor(Date.now() / 1000)
// Standard Webhooks: key is the base64-decoded part after whsec_
const swKey = Buffer.from(secret.replace(/^whsec_/, ''), 'base64')
const swSig = createHmac('sha256', swKey)
.update(`${msgId}.${ts}.${body}`)
.digest('base64')
const headers: Record<string, string> = {
'content-type': 'application/json',
'webhook-id': msgId,
'webhook-timestamp': String(ts),
'webhook-signature': `v1,${swSig}`,
}
if (legacy === 'send') {
// Old scheme: raw secret string as key, hex digest of the body only
const legacySig = createHmac('sha256', secret).update(body).digest('hex')
headers['x-acme-signature'] = `sha256=${legacySig}`
}
return headers
}
Look at the legacy parameter. You decide it per endpoint and per attempt, and the probe and the brownout below both depend on that.
The receiver's fallback is a downgrade path
Now the receiving side. The obvious migration code checks the new header and falls back to the old one. It works, and it has a hole that depends on what the old scheme lacked.
If the old scheme signs the body only, with no timestamp, a captured request stays valid forever. An attacker who has one old delivery strips the webhook-* headers, replays it with only the legacy header, and your fallback accepts it. Your new scheme's replay protection exists on paper and nowhere else.
If the migration is purely an algorithm swap, the risk is smaller than people assume. SHA-1 collisions are practical. Forging an HMAC-SHA1 is not. Immuta's move was hygiene, and nobody needed to panic. But migrations to Standard Webhooks usually add a timestamp, and that is exactly the property a fallback throws away.
Pin the new scheme once it arrives
Treat it like HSTS. Once a sender has started including the new header, stop accepting deliveries without it. Log which path verified each request so you can see the legacy path go quiet before you delete it.
import { createHmac, timingSafeEqual } from 'node:crypto'
const REQUIRE_NEW_SCHEME = process.env.ACME_REQUIRE_NEW_SCHEME === 'true'
function safeEq(a: string, b: string): boolean {
const ab = Buffer.from(a)
const bb = Buffer.from(b)
return ab.length === bb.length && timingSafeEqual(ab, bb)
}
export function verify(secret: string, h: Record<string, string | undefined>, body: string) {
const id = h['webhook-id']
const ts = h['webhook-timestamp']
const sigs = h['webhook-signature']
if (id && ts && sigs) {
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return { ok: false, via: 'new' }
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64')
const expected = createHmac('sha256', key).update(`${id}.${ts}.${body}`).digest('base64')
const ok = sigs.split(' ').some((s) => s.startsWith('v1,') && safeEq(s.slice(3), expected))
return { ok, via: 'new' }
}
if (REQUIRE_NEW_SCHEME) return { ok: false, via: 'missing-new' }
const legacy = h['x-acme-signature'] ?? ''
const expected = 'sha256=' + createHmac('sha256', secret).update(body).digest('hex')
return { ok: safeEq(legacy, expected), via: 'legacy' }
}
Two details matter. The webhook-signature header can hold several space-separated signatures, which is how Standard Webhooks handles key rotation, so check each one. And when the new header is present but wrong, the function does not fall through to the legacy check. A bad new signature means reject. Trying the weaker one next is how the downgrade gets back in.
Give every endpoint its own migration state
Back on the sending side. A global switch for the legacy header forces one sunset date on everyone. Store the state per endpoint instead.
ALTER TABLE endpoints
ADD COLUMN legacy_signature text NOT NULL DEFAULT 'send'
CHECK (legacy_signature IN ('send', 'omit')),
ADD COLUMN legacy_probe_passed_at timestamptz,
ADD COLUMN legacy_probe_failed_at timestamptz;
New endpoints start at omit. They have never seen the old header and never will. Existing endpoints start at send and move individually. Your sunset turns into a burn-down chart. The date you announce is when the last stragglers get switched. Everyone else moved weeks earlier.
Probe with a ping you are willing to lose
Here is the signal a 2xx can't give you on real traffic. Send a test event with the legacy header omitted, exactly as it will look after the sunset. Then read the response.
If the endpoint returns 2xx, it either verifies the new header, accepts either, or verifies nothing. In all three cases it survives the sunset. If it returns 401 or 403, it depends on the legacy header, and now you know which customer to email before you break them.
Use an event type with no side effects. Most senders already have one, such as a ping or a test delivery from the dashboard. Do not probe with a real invoice.paid.
Two blind spots. Receivers that acknowledge first and verify later in a worker return 2xx no matter what, so the probe passes and the failure shows up in their worker logs, where you will never see it. And some handlers skip verification for ping events entirely. A passed probe is strong evidence. It still isn't proof, which is why the brownout comes next.
Brownouts beat deadlines
API teams have retired endpoints with scheduled brownouts for years: turn the old thing off for an hour, watch who screams, turn it back on. It works even better for webhooks, because you already have a retry schedule.
Pick a batch of endpoints whose probe passed. Omit the legacy header on first attempts for thirty minutes, and keep sending it on retries. An endpoint that still depends on it rejects the first attempt. The retry carries both headers and succeeds. Nobody loses an event, and you get a per-endpoint list of real failures to compare against the probe results.
This only works if the header set is computed per attempt, which is why signAttempt takes legacy as an argument. It also only works if your failure accounting is per endpoint. A brownout that shows up as a 0.4% bump on the global error rate tells you nothing.
The shared secret outlives the migration
One last thing to put on the timeline. If your new scheme is asymmetric, like the v1a Ed25519 signatures in Standard Webhooks, a big part of the payoff is that a receiver-side leak can't be used to forge deliveries. You only get that payoff once the last legacy HMAC header is gone. Until then you hold a shared secret per endpoint, and so does every receiver, and anyone who steals one can sign the legacy header that some receivers still trust.
That changes how you plan the sunset. The dual-signing period costs you something every day it runs. For every receiver that hasn't pinned the new scheme, your security is whatever the weaker one gives you.
Dual-signing forever is also a decision
GitHub added X-Hub-Signature-256 in 2020 and still sends the SHA-1 X-Hub-Signature next to it. That is a choice, and for GitHub's ecosystem of abandoned integrations it may be the right one. The cost is permanent: two code paths, two headers to document, and a legacy option every new integrator will see and some will pick.
If you choose to keep the old header indefinitely, write that down as a decision with an owner. What you should not do is turn on compat signatures in October, forget about them, and discover in three years that half your receivers verify the scheme you meant to retire.
Frequently asked questions
Should the compat signature use a separate secret from the new one? It can, but then every receiver has to fetch and store a second secret, which is the migration cost dual-signing exists to avoid. Hookdeck reuses the destination secret for that reason. If you do split them, make sure the legacy secret is revoked at the sunset and not left active in your database.
How long should a dual-signing period last? Long enough for your probe and brownout data to cover most endpoints, which usually takes months. Immuta went from opt-in to mandatory in about three months with an enterprise customer base. A self-serve platform with thousands of small integrators needs more, and should only set the date once the burn-down is in.
What should a receiver do if the new header is present but fails verification? Reject it. Falling back to the legacy header when the new one fails turns any bug or attack on the new path into a silent downgrade. Log the failure with the webhook-id so you can tell a key mix-up apart from a forged request.
Can I probe an endpoint that is already failing or disabled? No, fix the endpoint first. A disabled or failing endpoint returns errors for reasons unrelated to signatures, so the probe result is noise. Re-enable it, let real deliveries succeed for a while, and probe afterwards.