Idempotency Keys End-to-End: API Gateway Through Step Functions Safely

POST /v1/orders HTTP/1.1
Idempotency-Key: 018f3c2a-9c1e-7b2d-a111-deadbeefcafe
Content-Type: application/json

{"sku":"sku-1","qty":2}

# api/handler.py
import hashlib, json, os, re
import boto3
from botocore.exceptions import ClientError

sfn = boto3.client("stepfunctions")
KEY_RE = re.compile(r"^[A-Za-z0-9._-]{8,128}$")
SM_ARN = os.environ["SM_ARN"]

def handler(event, _):
 key = event["headers"].get("idempotency-key") or event["headers"].get("Idempotency-Key")
 if not key or not KEY_RE.match(key):
 return {"statusCode": 400, "body": '{"error":"idempotency_key_required"}'}
 body = event.get("body") or "{}"
 payload = {
 "idempotency_key": key,
 "body_hash": hashlib.sha256(body.encode()).hexdigest(),
 "body": json.loads(body),
 }
 try:
 # ✅ Execution name enforces uniqueness per state machine
 sfn.start_execution(
 stateMachineArn=SM_ARN,
 name=key,
 input=json.dumps(payload),
 )
 except ClientError as e:
 if e.response["Error"]["Code"] != "ExecutionAlreadyExists":
 raise
 # same key → return prior status (fetch describe_execution)
 return {"statusCode": 202, "body": json.dumps({"id": key})}

# ❌ Blind StartExecution without hashing body
sfn.start_execution(stateMachineArn=SM_ARN, input=body)

from aws_lambda_powertools.utilities.idempotency import (
 IdempotencyConfig, DynamoDBPersistenceLayer, idempotent_function,
)

persistence = DynamoDBPersistenceLayer(table_name=os.environ["IDEMP_TABLE"])
config = IdempotencyConfig(event_key_jmespath="idempotency_key", expires_after_seconds=86400)

@idempotent_function(data_keyword_argument="event", config=config, persistence_store=persistence)
def charge(event: dict) -> dict:
 return payment_provider.charge(event["body"])