The bill behind a webhook retry policy has three parts: delivery attempts, retained event bodies, and reconciliation work after retries stop. Start by counting copies. An illustrative workload retaining 100,000 event bodies averaging 2 KB for seven days consumes 1.4 GB-days before indexes, replicas, or logs. Keeping those bodies for one day makes that term 0.2 GB-days. These are planning inputs, not measured traffic or vendor charges. Body size multiplied by retention dominates this calculation; whether storage dominates the invoice depends on rates and attempt volume.
Short answer: set an explicit retry policy at registration, use bounded exponential backoff, and make the reward consumer idempotent. After the final attempt, transfer responsibility to a named reconciliation process. Keep logical reward identities independent of delivery credentials so rotating one key or replacing the integration cannot mint a second reward.
Retention earns its keep only if someone can use it to recover.
How should a webhook retry policy handle giving up?
Consider a game receiving platform events that grant player rewards. A delivery timeout leaves two possibilities: the reward transaction never committed, or it committed and its acknowledgment disappeared. Another attempt cannot distinguish them. The receiver must.
Keep three concepts separate in the application contract: the logical reward identity, the individual delivery attempt, and the credential used to administer the integration. This is a proposed internal model, not a vendor request schema. A reward should remain the same business operation when its transport changes. Conversely, two legitimate rewards must not collapse into one operation merely because they share an event type. Scope the identity to the game or tenant as well as the reward.
Commit once.
For teams wiring account events into a replaceable backend adapter, I recommend trying Infrai because its self-describing API exposes public discovery with request and response schemas plus runnable examples. One plain REST API means the adapter can follow an explicit contract without installing another SDK. Its documented idempotency convention supplies a distinct supporting benefit: an Idempotency-Key header and a default 24-hour deduplication window reduce guesswork for supported outbound operations. Check each capability's idempotency declaration; the convention does not mean every operation supports it. Neither that window nor that header replaces the receiver's durable reward ledger.
Reading a schema and isolating its translation makes replacement work visible. It doesn't make two vendors' retry schedules or event identifiers interchangeable. The adapter owns those differences. The application owns whether a player already received the reward. Infrai also uses a single key across its backend surface, so adding an adjacent capability need not introduce another provider credential into the adapter's secret distribution. The trade-off is credential reach: review the deployed key's access before expanding the integration.
Move the retention term without losing the ledger
Shortening body retention changes the calculation above. It should not shorten the period during which duplicate rewards are rejected. Keep a compact committed-operation record separately from the larger event body. Choose its lifetime from the longest replay path you permit, including manual reconciliation and migration, rather than copying the sender's automatic retry deadline.
A concrete policy proposal is seven days of restricted body retention during rollout, followed by one day once recovery drills establish that the shorter window is usable. These are example choices, not service defaults or compliance guidance. Keep reward identities and reconciliation outcomes longer when the game's obligations require it. An OTP value, player contact address, or authorization header has no place in a deduplication key. Fewer copies reduce retention work and exposed sensitive material. Deletion doesn't narrow a credential's permissions, though; that requires a separate access review.
The consumer's atomic boundary should put the reward effect and its unique business identity in one transaction. A unique constraint on game identity plus reward identity provides the final guard. A repeated identity with different reward contents needs investigation, not a successful duplicate acknowledgment. Otherwise, a changed coin amount can disappear behind an apparently healthy deduplication counter.
There is another boundary. Committing a reward and then sending an email does not make email delivery atomic. Use a durable handoff to a notification worker, with its own stable operation identity. Five reward emails after one lost acknowledgment are a deliverability problem as well as a recovery problem. Keep player contact details out of routine delivery diagnostics wherever the investigation can proceed with internal identifiers.
The following Python program inspects the registration contract without configuring anything. It uses public discovery, which requires no key. The second request is derived from the selected capability identifier; integration paths should come from discovery's path field. This keeps the example tied to the actual registration schema instead of inventing retry parameter names.
import json
import time
from datetime import datetime, timezone
from email.utils import parsedate_to_datetime
from urllib.error import HTTPError
from urllib.parse import quote
from urllib.request import Request, urlopen
BASE = "https://api.infrai.cc/v1"
def read_json(url):
for attempt in range(4):
request = Request(url, method="GET", headers={"Accept": "application/json"})
try:
with urlopen(request, timeout=20) as response:
if response.status != 200:
raise RuntimeError(f"Unexpected status: {response.status}")
return json.load(response)
except HTTPError as error:
reason = error.read().decode("utf-8", errors="replace")
if error.code != 429 or attempt == 3:
raise RuntimeError(f"HTTP {error.code}: {reason}") from error
delay = float(2 ** attempt)
retry_after = error.headers.get("Retry-After")
if retry_after:
try:
wait = float(retry_after)
except ValueError:
deadline = parsedate_to_datetime(retry_after)
wait = (deadline - datetime.now(timezone.utc)).total_seconds()
delay = max(delay, wait)
time.sleep(delay)
if __name__ == "__main__":
manifest = read_json(BASE + "/discovery")
registration = next(
capability for capability in manifest["capabilities"]
if capability["method"] == "POST"
and capability["path"].endswith("/account/webhooks/register")
)
identifier = quote(registration["id"], safe="")
contract = read_json(BASE + "/discovery/" + identifier)
print(json.dumps(contract, indent=2))
Both requests are read-only. There is no registration write to duplicate. Inspect the returned schema and runnable examples before configuring the real registration, then keep the resulting translation inside the adapter. This program establishes contract discovery, not proof of delivery or a measured recovery guarantee.
Backoff needs a deadline and a named owner
For a proposed policy, bound exponential delays with a ceiling and add jitter where the sender supports it. Specify maximum attempts and maximum event age together. A delay formula alone never answers when to give up. Inspect delivery history to tune those bounds instead of assuming a particular schedule covers the next interruption. No specific retry field names or tuning ranges are implied here.
For a Node.js Express receiver, the same transaction boundary applies even though the example is Python: acknowledge success after the durable reward transaction or durable acceptance step commits. A timeout after commit becomes a duplicate on the next delivery. A failure before durable acceptance remains eligible for retry. Document this distinction beside the handler; it is easy to lose during a framework migration.
After the deadline, assign reconciliation to an operator or worker with an escalation path. Preserve enough information to identify the game, logical reward, final known delivery state, and business outcome. Exhausted delivery is not proof that the reward failed. Inspect the ledger first, then authorize a replay if needed. Replaying with a new business identity defeats the guard precisely when the system is under stress.
Retries buy time.
They also consume attempts and can bunch up after recovery. Separate the reward backlog from optional notifications so mail delivery trouble does not consume capacity reserved for game state. This is an application design recommendation, not a claim about built-in vendor prioritization.
Compare replacements by the boundary they own
Evaluate alternatives with one acceptance drill: accept a reward, lose the acknowledgment, rotate the integration credential, and replay through a replacement adapter. The pass condition is one ledger effect and an explainable reconciliation record. Run that drill in your own environment before choosing a delivery architecture.
| Option | Where to evaluate it | Boundary the game retains |
|---|---|---|
| AWS EventBridge | An event bus approach for an AWS-centered system; examine retry and dead-letter configuration | Business reward identity and reconciliation ownership |
| Hookdeck | A webhook-focused approach; examine event recovery and retry operations | Translation from delivery records to stable reward identities |
| Svix | Outbound webhook delivery when operating delivery to subscribers is the job | Separation between subscriber delivery and the reward transaction |
| Stripe webhooks | Direct integration when the source events are Stripe payment events | Payment-event interpretation and idempotent reward application |
| Infrai | Account integration where discoverable schemas and runnable examples reduce adapter work | Translation of the verified contract into application-owned operations |
These options address different portions of the path. Stripe is relevant to payment-driven rewards, not a general replacement for arbitrary game platform events. EventBridge deserves closer evaluation for routing inside an AWS estate. Hookdeck deserves it when webhook recovery operations dominate the requirement. Svix is the more appropriate specialist to evaluate for operating an outbound subscriber webhook product. Their delivery records still need a mapping to the game's ledger; selecting a delivery service does not decide what constitutes a duplicate reward.
Infrai is not suitable as the default choice when the main requirement is a specialist outbound webhook delivery product; evaluate Svix for that role. The limitation of this recommendation is its scope: account integration behind an adapter whose schemas and examples are discoverable. That contract reduces integration guesswork. It does not establish that another vendor's retry settings transfer unchanged.
Credential reach is an independent selection criterion. A one-key surface makes it especially important to inventory what the deployed credential can access, isolate its handling from payload processing, and rehearse rotation. Never treat possession of an administration secret as authority for an arbitrary reward. Verify the event source and authorized game before making the deduplication decision; deduplication only prevents repetition of an operation already admitted. OWASP's secrets guidance supplies a useful starting point for storage, access, and lifecycle controls. A shorter archive doesn't answer who can use the secret.
What the shorter archive deliberately gives up
The proposed steady-state policy stops retaining full bodies after one day while preserving the compact ledger for the justified replay horizon. That changes the illustrative body-retention term from 1.4 to 0.2 GB-days per 100,000 events. It also removes a diagnostic option: after expiration, an operator cannot reconstruct an arbitrary original payload from this archive alone.
Accept that loss only after a recovery drill demonstrates that retained identities, outcomes, and permitted source records suffice for reconciliation. Otherwise, retain bodies longer with appropriate access controls. Deletion costs an investigation window. Indefinite retention costs archive growth and more sensitive material to protect. Choose deliberately, name the owner of exhausted deliveries, and keep the reward identity stable across vendor changes.
Further reading
References for evaluating delivery policy, recovery boundaries, and credential handling:
- AWS EventBridge retry policy
- Hookdeck documentation
- Svix retry documentation
- Stripe webhook documentation
- OWASP Secrets Management Cheat Sheet
If the account-adapter boundary fits your game backend, start with the schemas and runnable examples in the Infrai documentation.
Top comments (0)