Skip to main content

November 13, 2026

Webhook dedupe keys need signed bytes

HR webhooks retry for a day. My dedupe key had to come from signed body bytes, not headers or picked JSON fields. Review caught all three mistakes.

Sander Korf5 min read
nextjsvercelworkflowstypescript

A retail company runs an internal service I was wiring in Next.js: when their HR platform sends employee lifecycle webhooks (hire, contract change, termination), each delivery is a small JSON envelope. My route handler verifies an HMAC signature, strips personal fields with a Zod allowlist, and starts Vercel Workflows with start(), a durable workflow run whose steps survive restarts, that will eventually fetch the full person record from the HR API and compute what downstream HR tools should receive. The first milestone only logs intent, no writes yet.

The vendor redelivers on non-2xx, dropped connections, or slow answers, with exponential backoff across roughly a day. I was trying to return HTTP 200 quickly, dedupe identical copies, and still let the next legitimate update through for the same employee. Automated code review on the branch then asked what stops replaying a valid signed body while swapping the unsigned tracking header. That comment kicked off three different ways my dedupe key had been lying. None of it reached production.

What the vendor actually signs

The integration docs define signature as HMAC-SHA256 over the string POST plus the raw body bytes, sent as hex in a header and compared in constant time. Headers are not inside that MAC. Delivery fails on non-2xx, connection errors, or no response within thirty seconds, then retries from one minute up to sixteen hours. Ten consecutive failures disable the subscription. I had already written about answering fast versus hydrating sparse payloads in Sparse webhooks need hydrate or a 503 retry. Here the puzzle is the idempotency key: a stable string that means "this exact delivery," stored as a workflow hook token so a second pass can claim or skip work.

An idempotency or dedupe key is only useful if the route enforces it before start(). My first sketch joined vendor id, event type, and a tracking fragment into a string and passed it only as workflow input. Nothing called getHookByToken. A lost HTTP response after a successful start meant the vendor could open a second workflow run for the same signed payload.

Enforcing the key across the retry window

The next version preferred an unsigned tracking-id header, then a tracking id inside the body, then a sixteen-character prefix of SHA-256 over hand-picked fields { eventType, createdAt, profileId ?? contractId }. I wired enforcement: the route calls getHookByToken(key) and returns { status: 'duplicate' } when the token is still held. Inside the workflow, createHook({ token: key }) exits on conflict when two redeliveries race, then sleep('1d') keeps the token through the vendor retry window. If every resource step fails, the run throws, releases the token, and an honest retry can enter. Dedupe lookup or start failures return 503 so the vendor's delivery pipeline schedules another attempt later.

That looked production-ready until automated code review peeled the assumptions apart.

Three ways the key lied

Key too coarse. Distinct updates for the same person shared the fallback field hash because employment status never entered the picked object and profileId ?? contractId dropped the contract id when a profile id existed. The first workflow held the hook for a day, so a later legitimate status change returned duplicate and never ran.

Key attacker-shaped. The HMAC authenticates POST plus body, not the tracking header. A captured valid delivery replayed with a forged header value minted a fresh key, bypassed duplicate checks, and repeated HR API reads and workflow work.

Key decorative. Before enforcement, the string was metadata only. Same signed redelivery after a dropped response still meant two runs.

The final rule matches what the MAC already committed to: use the tracking id inside the signed body when present, otherwise the first sixteen hex chars of SHA-256 over the raw body string. Identical redeliveries collide, distinct updates diverge, header edits on replay do not.

Try the three columns in the demo: run Redeliver same signed body twice, then Replay with edited header, then Send real status change and watch which strategies get a red wrong badge.

Simulation

Which dedupe key survives?

Fake HR lifecycle webhook: HMAC covers POST plus body only. Headers are editable on replay.

Delivery actions

Signed body (excerpt)

{"contractId":"c-9","createdAt":"2026-10-01T12:00:00Z","employmentStatus":"active","eventType":"employee.updated","profileId":"p-42","trackingId":"trk-100"}

Unsigned header tracking id: trk-100

Unsigned tracking header

No delivery yet.

Hash of chosen fields

No delivery yet.

Body id or raw-body hash

No delivery yet.

Run an action. Signed bytes column should accept only the status update and treat header replays as duplicate.

const key = envelope.trackingId ?? sha256Hex(rawBody).slice(0, 16)
if (await getHookByToken(key)) return Response.json({ status: 'duplicate' })
await start(lifecycleWorkflow, [{ key, ...sanitized }])
// workflow: createHook({ token: key }), work, throw if all steps fail, await sleep('1d')

Dedupe failures and workflow start errors still map to 503, same pattern as refusing to ack without hydrated data. Step boundaries still eat rich errors unless you encode them, as in Vercel Workflows: typed errors lost at steps.

Nothing here shipped broken. Automated code review on the branch caught each variant before merge. No header-only build went out, no replay exploit, no silent drop of real updates in a live environment.

Webhook dedupe material has to come from the same byte string the signature verified, or from an id that lives inside that string. Anything outside the MAC is decoration.


Happy coding! Sander