At 8:40 on a Seattle morning, integrations engineer Nina has twenty minutes before a customer appreciation batch can leave its approval queue. A Stripe endpoint signing secret is due to be retired. Her choice is consequential: keep a documented overlap long enough to prove the new verifier, or revoke the old secret immediately and hold affected processing. Either way, a valid replay must not create a second gift order.
The useful result is a verified change in who can authenticate an incoming request, accompanied by evidence that the same approved occasion still produces one business intent. That requires two separate controls: provider-specific signature verification and an internal approval ledger. A successful response from a webhook endpoint proves neither gift eligibility nor successful fulfillment.
Decide whether overlap is appropriate before touching the key
Stripe’s webhook documentation currently offers an immediate expiration or a delayed expiration of the existing endpoint signing secret, with a delay of up to seven days. During the selected overlap, Stripe signs with each active secret. Treat that documented maximum as a capability, not a recommended maintenance duration. Choose the shortest tested window that suits your deployment, and check the current console and documentation when executing the change.
Nina’s scheduled rotation assumes no evidence that the old secret has been exposed. She chooses a brief, documented overlap so that a deployment can accept the new signature before the old secret expires. If exposure is suspected, the security incident owner must decide on immediate revocation and containment. Continuing to trust a compromised secret merely to keep a gift batch moving would defeat the purpose of the change.
Define the exact endpoint and environment first. A test endpoint secret is not a live endpoint secret. Two endpoints serving similar events do not thereby share one verification configuration. Record an opaque configuration version and the endpoint identity in the change record; keep the actual secret in the approved secret store. A screenshot containing the value is not useful acceptance evidence.
The change window should have a named technical owner, an approval owner, and a fulfillment contact. The technical owner changes verification configuration. The approval owner decides whether an authenticated event represents a still-approved occasion. The fulfillment contact reconciles any existing external request whose outcome is uncertain. Those responsibilities can belong to a small team, but they should not collapse into an unreviewed “retry everything” action.
Separate request authentication from permission to send
Use a staged path: receive the unmodified request, verify it with the appropriate official library and endpoint configuration, durably record accepted intake, evaluate business approval, and create an outbound intent through a controlled worker. Do not parse and reserialize the body before signature verification. Middleware that changes bytes can make a genuine request fail verification; accepting the changed body without verification is not a repair.
Keep these records distinct. A delivery attempt records what reached your endpoint and the verification result. A provider event record identifies a verified source event. An approval record identifies the recipient, occasion, permitted budget and current decision. A gift intent is the single internal instruction authorized by that approval. A fulfillment record captures the actual external outcome. None should silently stand in for another.
Stripe documents duplicate delivery and also notes that separate Event objects can sometimes concern the same underlying object and event type. Recording an event ID is useful, but it does not define your entire gifting policy. A business key should identify the approved award occasion at the scope your organization actually intends: for example, a tenant, a campaign, an approved recipient reference and an eligibility period. Establish that scope with the program owner.
A customer ID alone can suppress legitimate future gifts. An event ID alone can allow two distinct source events to authorize the same award. An email address can change and may not be an appropriate durable identity. An amount can repeat across unrelated purchases. These are reasons to define a stable approval key, rather than reasons to invent one universal key for every program.
| Record | Question it answers | Evidence to retain |
|---|---|---|
| Verified intake | Did this request pass the exact endpoint verifier? | Event reference, configuration version and result |
| Business approval | Is this occasion still eligible? | Approval key, policy version and decision |
| Gift intent | Has this approved occasion already entered dispatch? | Unique intent reference and state |
| Fulfillment result | What actually happened outside the ledger? | Confirmed external reference or unresolved outcome |
Access and retention should fit the sensitivity of each record. Prefer opaque references in a routine change report. If raw payloads are necessary for a bounded investigation, protect them through the organization’s existing controls and remove them according to its retention policy. A debugging convenience is not permission to copy recipient data into a widely shared ticket.
Worked decision one: prove the overlap without counting attempts as gifts
For a rehearsal, assume Nina’s test harness submits seventy-two HTTP attempts. Sixty are first deliveries of distinct valid events, eight are valid repeat deliveries of those events, and four have invalid signatures. Of the sixty verified source events, forty-six match approved gift occasions and fourteen require a business hold. These are explicit test inputs, not reported customer results.
The expected intake result is sixty distinct accepted source events, plus evidence of eight verified repeat attempts. Four invalid attempts remain outside accepted event processing. They can have restricted security diagnostics, but they must not be promoted into trusted replay jobs simply because their bodies resemble known events. Sixty-eight verified attempts are not sixty-eight eligible gifts.
The expected business result is forty-six unique intents and fourteen held decisions. A held business decision can coexist with an appropriately acknowledged verified, durably accepted webhook. Conversely, a verification failure must not receive the same successful processing treatment as a trusted event. Use the provider’s current response and retry contract; do not make fulfillment finish synchronously merely to produce an HTTP response.
Run a fresh request signed for the new configuration while the documented overlap is active. Record the verifier version that accepted it. Exercise the valid overlap path and a deliberately wrong endpoint secret. After retiring the old configuration, an old-only test request must fail the now-current verifier. Keep this test bounded to a controlled fixture; do not weaken timestamp checks or restore an expired secret in production to make a stale captured request pass.
Next, submit a repeat of an already accepted source event through a currently valid test delivery. The event should resolve to its existing intake record and existing business decision. It must not insert a second intent. To avoid a misleading test, distinguish a new delivery carrying a valid current signature from resubmitting an old signed byte sequence that the verifier should reject as stale.
Finally, reconcile outbound results. Suppose forty-five intents have confirmed external outcomes and one outbound call timed out. The expected state is forty-five confirmed and one unknown, still totaling forty-six intents. It is not permission to issue a forty-seventh instruction. Investigate the unknown intent against the actual downstream system before retrying, using its documented lookup or idempotency behavior where available.
If that investigation finds an existing successful external order, attach its reference to the original intent. If it proves no order exists and a retry is authorized, retry that same intent under the actual downstream contract. If neither fact is established, hold that intent. Other independently approved, unambiguous work can continue. An unresolved timeout should not become either an invented success or a blind replacement order.
Worked decision two: two provider events can represent one award
A Boston revenue operations team uses a separately approved renewal appreciation program. Assume two distinct verified Event IDs relate to one underlying renewal occasion. Event-level deduplication accepts each source event once, as it should. The business approval ledger, however, identifies one approved award key for the same recipient, campaign and eligibility period.
The first worker creates an intent against that key. The second worker must discover the existing intent, even if both workers arrive concurrently. A read followed by an unguarded insert is insufficient: both workers can read “absent” before either inserts. Implement the uniqueness and state transition atomically in the actual database or equivalent transactional system. Record the duplicate-key outcome as reconciliation, not as a second approval.
For this test, assume there are two source events, one approval key, one intent and one confirmed external order. Those four counts answer different questions. The second event remains traceable to the first approved occasion without erasing its original source identity. The operations team can explain why both events were accepted while only one gift instruction was permitted.
Now change the fixture: the same recipient has a separately approved occasion in another campaign or policy period. That can be a legitimate second award. The test must prove the key distinguishes those occasions rather than treating all gifts to a person as duplicates forever. Have the program owner approve the key’s scope before relying on it during a rotation.
Also test a late event after the approval has been withdrawn. Signature verification still establishes source authenticity; it does not reinstate approval. Read the current authoritative business state and apply the existing cancellation or hold process. Do not reverse a shipped order by changing an intake row, and do not send a replacement merely because an earlier event was replayed.
The broader eligibility decisions belong in the adjacent Stripe renewal gifting workflow. The narrow acceptance question here is whether changing the verifier preserves that already-defined approval decision. Keeping the two decisions separate prevents a routine security change from quietly rewriting the program’s spending rules.
Make failure states observable before reopening dispatch
A useful cutover rehearsal includes more than a green happy-path response. Test a modified request body, a missing or invalid signature, a valid signature for the wrong endpoint, a valid new configuration, a repeated accepted event, concurrent workers, a database outage, an outbound timeout and a later change in approval. Each should have a predicted state and an owner who can explain the result.
For a database failure before durable intake, do not claim the event has been accepted merely because the process held it in memory. Follow the provider’s current retry behavior and your tested response policy. For a durable accepted intake whose approval evaluation is pending, preserve that state and let the worker resume. Do not delete the accepted record in an attempt to “start clean.”
For a signature failure after deployment, first compare endpoint identity, environment and configuration version. Then check whether middleware preserved the original request bytes and whether the deployed secret reference is correct. A failure is not evidence that signature verification should be disabled. Keep downstream dispatch closed for the affected path until a current valid fixture passes and the rejected fixture still fails.
For an uncertain external result, preserve the outbound request reference, time, intent identity and response uncertainty. Avoid logging secret material or unnecessarily exposing recipient details. The operator needs enough information to reconcile the actual request, not a second payload assembled from a spreadsheet. Any authorized retry should remain attached to the original intent and the downstream system’s real guarantees.
Rollback needs its own definition. Reverting an application deployment does not necessarily make an expired provider secret valid again. Maintain a tested path to a currently valid configuration. If returning to an earlier application version would remove the new verifier, hold affected dispatch while repairing that version or deploying a corrected one. Do not label an unverified rollback “restored.”
Use an acceptance ledger with explicit arithmetic
A change report should let another engineer reproduce the conclusion without access to the secret itself. Include the provider documentation checked, endpoint and environment identifiers, configuration versions, planned expiration, actual deployment time, test fixture references and the person who reviewed the business-key scope. Record actual values from execution rather than filling the template with expected results.
| Acceptance question | Expected result in the first rehearsal | Release consequence |
|---|---|---|
| Were first valid events durably accepted? | 60 distinct source events | Investigate any missing intake |
| Were valid repeats reconciled? | 8 repeats, no additional source identities | Hold if repeats create new intents |
| Were invalid attempts excluded? | 4 rejected attempts | Keep dispatch closed if any are trusted |
| Were business decisions preserved? | 46 intents and 14 held decisions | Reconcile every mismatch |
| Were uncertain outbound results isolated? | 45 confirmed, 1 unknown initially | Hold the unknown intent until proven |
| Did the retired configuration stop working? | Old-only fixture rejected after retirement | Correct verifier deployment before reopening |
Do not add those columns together as if they were one inventory. Seventy-two HTTP attempts include repeat and invalid traffic. Sixty accepted source events include fourteen business holds. Forty-six intents can temporarily include one unknown external result. The ledger is valuable precisely because these categories remain visible instead of being compressed into one “success” count.
Have a reviewer other than the implementer inspect the exact deployed version and test outputs. The reviewer should verify both positive and negative results, the concurrency test and the uncertain-order reconciliation. A verbal assurance that “deduplication is already handled” is weaker than a trace from two competing inputs to one committed intent and its actual external reference.
The acceptance record should identify remaining limits. A fixture proves the tested path under stated conditions; it does not prove every possible downstream behavior. A database uniqueness constraint can protect one internal intent while an external system still needs its own reconciliation. Avoid describing the whole pipeline as exactly-once delivery unless that claim is supported across every boundary involved.
Preserve a trustworthy replay boundary
Keep the event's original source identity attached to every authorized reprocessing attempt. An operator may request a new evaluation after fixing an internal defect, but that request is a separate operational instruction, not a fabricated provider delivery. Record who authorized it, which accepted event it concerns, and which approval version will be evaluated. Require the same business uniqueness guard as ordinary intake.
A replay tool should not accept an arbitrary JSON file and silently mark it verified. Restrict it to previously accepted records or to a documented provider delivery path that receives normal verification. If a captured payload lacks trustworthy provenance, hold it for investigation. Matching a familiar customer name or order amount cannot establish authenticity.
Test permissions as well as data. A support operator who can inspect a failed intent need not be able to change verifier configuration or release a held gift. A technical deployment account need not approve new spending. Use existing organizational roles and record the actual controls; do not imply that a webhook library provides those business permissions automatically.
For the rehearsal, ask the reviewer to attempt an unauthorized replay and an authorized reevaluation of the same accepted event. The first must remain outside processing. The second must preserve the event and approval references and still resolve to the existing intent when the occasion has already been dispatched. This closes a practical gap: a perfect automated deduplication path can still be bypassed by a poorly controlled maintenance tool.
Close the change window without losing the next operator
Before Nina reopens the batch, she checks that the deployed verifier accepts current valid requests, the retired configuration is no longer trusted, and the approval ledger still reconciles. She records the unresolved-intent queue separately from completed work. A single held order remains assigned to its investigation owner rather than disappearing into the general rotation ticket.
Keep the expiration time visible in an operational record that contains no secret value. Remove obsolete configuration references through the approved configuration process once the retirement is verified. Alerting should distinguish a rise in authentication failures, intake persistence failures, approval holds and unknown outbound results. A single generic “webhook failed” counter leaves the next operator guessing which boundary is broken.
Choose monitoring duration from the provider’s current delivery and retry behavior and the program’s actual operating window. Do not assume all providers share Stripe’s retry or rotation rules. LINE, for example, documents different secret reissue behavior; a runbook copied across platforms can preserve the wrong trust window. Recheck provider-specific rules before each materially different integration change.
Nina’s opening decision is resolved when the planned overlap ends with a verified new configuration and preserved approval outcomes. If the suspected-compromise path had applied, the decision would instead be immediate containment and a controlled hold. The batch deadline does not alter which signatures are trustworthy, and a replay does not manufacture a new approved occasion.
Bring a verified gift brief to Giftpack
Once the internal decision is approved and reconciled, prepare the commercial brief separately: audience, countries, budget, timing, product restrictions and the review owner. Giftpack’s corporate gifting guidance describes campaign inputs, curated choices and human review, with sourcing and production constraints depending on the program. Confirm the actual fulfillment arrangement before promising a delivery outcome.
The engineering handoff should give the program team a stable approved instruction and a traceable outcome, without exposing webhook secrets or assuming an undocumented integration. Nina can then discuss an appropriate gifting program with Giftpack while keeping authentication, approval and external fulfillment evidence clear. One changed secret, one preserved decision and one reconciled intent is the useful finish.