Worked glossary use
In a review meeting, a teammate says a webhook is “safe to retry.” Ask which property they mean. Shared-secret signature verification checks that the message matches the provider’s MAC format under the signing secret. Replay resistance limits reuse of an old signed message. Idempotency stops a valid redelivery from creating another ledger effect. These are three separate checks. Put one test result next to each term in the ticket. Do not treat a single green webhook test as proof that all three checks pass.
Terms for money movement
An operation ID names one intended money move. A provider event ID names one notification about it. A ledger entry records one financial effect. These IDs serve different jobs and should be linked, not used as substitutes.
Checks to run
- Idempotency: repeated requests have the same intended effect; use an operation key and inspect the ledger.
- Object authorization: a user may access only the account or claim they are allowed to access.
- Replay resistance: an old valid message cannot be accepted as a fresh approval.
Source map
OWASP defines object-level authorization risk in API endpoints. NIST explains replay-resistant authentication. Stripe documents signed webhooks and event delivery. Use those sources for the security terms; use your own contract and ledger rules for the financial terms.
Add the glossary link to review tickets so engineers, testers, and finance staff use the same names. Record a concrete expected result beside each term. A word alone cannot settle a design decision.
Use a term in a test plan
Take “idempotency” and write a test in plain terms: submit the same money move twice with the same operation key; expect one ledger effect and the same stored result. Then take “authentication” and “authorization”: a valid login proves who sent the request, while a wallet ownership check decides whether that person may read wallet W-01. Test each separately. Keep a term’s source beside its definition, then add a local example beside the source. If a provider uses a word differently, name the provider and link its exact definition instead of merging unlike meanings.
Attach the scope to each definition
For a shared-secret HMAC, verification shows that the bytes match a MAC produced with the shared secret. Both sender and receiver hold that secret, so the MAC alone cannot distinguish which holder produced it. For idempotency, state the key scope, retained result, payload-change rule, and time window. For replay resistance, name the protocol and the nonce or freshness rule being tested. A payment operation can need multiple legitimate effects, such as debit, fee, and later reversal. Define each effect type before using one-effect assertions. Link financial terms to the contract and ledger rule that makes them true; a general security standard does not define a bank’s settlement state.
Primary sources
- OWASP API Security Top 10:2023
- NIST Digital Identity Guidelines, SP 800-63B
- Stripe webhook signature documentation
Next step
Add an operation ID, event ID, and ledger entry to one real design ticket so each term has a concrete test. Read the related guide. For a review of your own system, request a security review.