Signed webhooks for order write-back: an HMAC checklist

Short answer: sign every webhook with HMAC-SHA256 over timestamp.body, send the timestamp and signature in headers, and on the receiving side recompute the signature, compare it in constant time, reject anything older than five minutes, and process each event idempotently by its order ID.

Why write-back needs signatures

A write-back webhook changes business records: it marks an order as purchased and attaches a supplier cost. Anyone who can reach the endpoint could otherwise mark orders as fulfilled or inject false costs into your profit reports.

The checklist

1. Shared secret per source. Each integration gets its own secret, shown once at creation and stored only by the two parties.
2. Sign timestamp and body together. For example X-Signature: sha256=HMAC(secret, "<timestamp>.<raw body>"). Signing the raw bytes avoids JSON re-serialisation mismatches.
3. Reject stale requests. Refuse timestamps more than five minutes away from your clock to block replays.
4. Compare in constant time. Use your language's timing-safe comparison, never plain string equality.
5. Be idempotent. The same event may arrive twice; key your handler on the order ID and event type.
6. Answer fast, work later. Return 2xx quickly and queue the heavy work, so retries don't pile up.

Event types worth handling

• order.purchased — carries the Amazon order number and the purchase cost.
• order.skipped — the order was not bought (rule, price ceiling or manual decision) and needs attention on your side.

Cloverlight Order Bot sends both events signed this way, and its ingest API accepts orders from any software that can send JSON.