Idempotent Billing Infrastructure
for Stripe Events.

Where Standard Queues Break

Queues like Sidekiq, Celery, or BullMQ are great for best-effort jobs. Stripe webhooks are at-least-once. Without database-level state locks, concurrent retries collide and ordering breaks.

Retry Storms Create Duplicate State

Timeouts trigger automatic retries. If invoice.payment_failed processes twice, customers receive overlapping dunning warnings and support volume spikes.

export async function handleStripeEvent(req, res) {
  // 1. Ingest & verify signature instantly
  const event = stripe.webhooks.constructEvent(req.rawBody, signature, secret);
  
  // 2. Generate a stable key from event id with request metadata when present
  const idempotencyKey = event.request?.id
    ? `req_${event.request.id}_${event.id}`
    : `evt_${event.id}`;

  // 3. Attempt to acquire distributed database lock
  const lockAcquired = await Arcli.Mutex.acquire(idempotencyKey, { timeout: 5000 });
  
  if (!lockAcquired) {
    // 4. Safely ignore retry storms if worker is already executing
    return res.status(200).send("State locked. Duplicate suppressed.");
  }

  // 5. Route to deterministic scoring engine safely
  await Arcli.Worker.dispatch(event);
  
  return res.status(200).send("Acknowledged");
}

Deterministic Scoring

Once an event is safely ingested and locked, Arcli routes the payload to the deterministic churn scoring engine. Recovery workflows trigger on explicit, observable facts.

Dunning Orchestration

Effectively-once execution ensures that when a payment fails, the system triggers the appropriate SaaS dunning workflow with strong safeguards against duplicate recovery messaging.