Build an idempotency key from an event

Join a scope, a business id and a version into one stable, colon-separated key.

JavaScript Version 1.0.0 · MIT · by Oveyon · .md

build-an-idempotency-key.js
function idempotencyKey({ scope, id, version }) { return [scope, id, version].map(part => encodeURIComponent(String(part))).join(':'); }

Input & expected output

Input

{
  "scope": "order-confirmation",
  "id": "8812",
  "version": 1
}

Expected output

"order-confirmation:8812:1"

The edge case

Input

{
  "scope": "welcome",
  "id": "user:42",
  "version": 2
}

Expected output

"welcome:user%3A42:2"

Know the limits

  • Derive the key from the business event, never from time or randomness: a retry must send the same key.
  • Oveyon accepts 1–190 printable ASCII characters without spaces, as the Idempotency-Key header or the idempotencyKey body field. Encoding keeps every part inside that set.

The function above is the implementation used by the lab. The lab validates JSON types and caps size before execution; include equivalent validation when accepting untrusted input in your application.

Source & maintenance

Written by Oveyon for this edition of 1loc.dev; it is not part of the original collection. Copyright (c) 2026 Oveyon. MIT licensed.

Its file in the public edition: contents/build-an-idempotency-key.mdx in akamind/1loc, commit 0a77f131b22d. The function above is the implementation the lab runs and the tests exercise; the test suite checks that it is the code that file carries. Read the license.

Local fixture scope · Node.js 22.23.2 · reviewed October 28, 2026. No external service is required.

Keep exploring

Type two or more characters. Try “duplicate”, “webhook” or “retry”.