Pin Duplicate-Delivery Receipts Before You Extract a Webhook Alias

A billing module that verified webhook signatures and recorded deliveries into a ledger faced an issue during cleanup. Duplicate detection code remained in an older file, leading to a replayed event inserting a second ledger row. This failure was not due to a weak signature algorithm or a missing test, but rather a consequence of callers relying on a duplicate contract for repeated event IDs.

To prevent this issue, production logs often show three rules: a repeated event ID must return the first outcome and skip a second ledger write; signature header names can arrive under various aliases, with only a known alias allowed to pass; and raw body bytes are hashed before JSON parsing, with key order not affecting the stored receipt.

To avoid breaking these rules, receipts should be stored before any changes to the code. A proposed test suite keeps the first suite to four fixtures, each containing one receipt row with event ID, alias used, SHA-256 of raw body, and outcome label. These fields include accepted, duplicate, and rejected outcomes. The test set consists of a valid delivery with the primary signature alias and an unseen event ID, the same raw bytes and event ID sent again to ensure duplication, an unknown alias that must be rejected without adding a ledger row or expanding the seen set, and a known alias with a signature fragment that does not match the raw body hash prefix.

Extra rows should only be added after incidents demonstrate that the four fixtures do not cover the behavior. The goal is to create a stable pin for the extract, not a growing archive of provider quirks.