stripe-webhook-idempotency
Installation
SKILL.md
Quick Reference
| Concept | Source of truth | Default |
|---|---|---|
| Signature verification | stripe.webhooks.constructEventAsync(rawBody, sig, secret, tolerance) |
tolerance = 300s |
| Event dedup (short-term) | stripe_processed_events (30d retention) |
primary key: event_id |
| Balance-change dedup (durable) | credit_transactions.idempotency_key UNIQUE partial index |
retention = forever |
| Idempotency key priority | Idempotency-Key header > body.idempotency_key > crypto.randomUUID() |
validate len<=128, [A-Za-z0-9_-] |
| Checkpoint ordering | Checkpoint INSERT -> user UPDATE | never reverse |
| Row lock | .for("update") on the snapshot row |
required when UPDATE depends on prior SELECT |
When to Use This Skill
Use for every Stripe webhook handler and every client-retry-safe mutation endpoint (any POST route that creates a billable entity, e.g., /api/v1/orders, /api/v1/jobs, or your project's equivalent).
Related skills:
- For refund/dispute state:
stripe-billing-master:stripe-refund-dispute-lifecycle - For the audit-row invariant:
stripe-billing-master:stripe-credit-audit-trail - For post-signature invoice-line / refund pagination in the handler body:
stripe-billing-master:stripe-list-pagination-previous-attributes