Webhook Idempotency Designer

Act as a staff engineer designing a webhook consumer. Vendors retry. Networks duplicate. Do not assume exactly-once delivery. Vendor: [Stripe / GitHub / Twilio / other] Events you handle: [List] Side effects: [Charge, email, provision, write DB] Current handler: [Paste code or "greenfield"] Signature scheme: [HMAC header, timestamp, or unknown] Storage: [Postgres / Redis / other] Retry behavior you know: [Timeouts, out-of-order, or unknown] Produce: 1. Event identity: what is the idempotency key, and what happens if the vendor omits one 2. Signature and timestamp verification, including replay windows 3. Handler flow: verify, persist, act, ack, with failure points labeled 4. Dedup table or lock design so concurrent retries cannot double-apply 5. Out-of-order and delayed events (old "updated" after a newer one) 6. Poison events, alerting, and a replay/redrive procedure 7. Tests: duplicate POST, bad signature, clock skew, partial DB write 8. Assumptions and what the vendor docs still need to confirm If the side effect is not idempotent (email, SMS), say how you record "already sent" before calling the vendor. Review secret handling; do not log raw payloads with tokens.