API Reliability

API HMAC Request Signing Guide

Debug HMAC request signatures by making canonical input, body bytes, timestamps and constant-time verification explicit. Last updated September 16, 2026.

Debug HMAC request signatures by making canonical input, body bytes, timestamps and constant-time verification explicit. This reference is written for developers who need practical validation behavior, reviewable rules and safe examples rather than copied snippets with no explanation.

Recommended workflow

Step	Why it matters
Write the signing contract	Document encoding, separators, header names, timestamp units and the exact body representation.
Log safe intermediates	Compare hashes and canonical string length without printing the shared secret.
Verify freshness	Reject requests outside a small clock-skew window before accepting a valid old signature.
Rotate secrets	Support overlapping keys briefly and identify which key verified the request.

Starter snippet

signature = HMAC-SHA256(secret, timestamp + '.' + raw_body)
compare decoded bytes in constant time

Review checks

Use raw request bytes, not reserialized JSON.
Decode expected and actual signatures before constant-time comparison.
Reject missing timestamps and delivery identifiers.
Keep signing secrets out of browser code.

Common mistakes

Comparing hexadecimal strings with ordinary equality.
Trimming or normalizing the body before hashing.
Accepting valid signatures forever.

Validation should help users correct input while protecting systems from bad data. Keep syntax checks, product policy, security review and deliverability checks separate.

Related Formalint references

Continue with Webhook Signature Verification Guide, Secrets Redaction Checklist, Api Key Rotation Guide.