Webhooks And Async Workflows

SyntaxKit ships exactly one inbound webhook: Stripe. It's signature-verified, deduped at two levels (event id and semantic side-effect key), and recovers crashed workers through a stale-claim window. Every coordination decision lives in Postgres, never in lambda memory, so it survives timeouts, OOMs, mid-flight deploys, and concurrent deliveries.

Async workflows (cron, durable queues, long-running tasks) don't ship today. The Async Workflows section covers Next's after(), the reusable OutboundEffect dedupe pattern, and the providers buyers most often plug in.

The Stripe webhook

Endpoint, signature verification, and how it delegates to the handler.

Two-layer idempotency

Event-id and semantic side-effect keys keep retries from double-firing.

Add a Stripe event

Register a handler, wrap side effects, and subscribe in Stripe.

Async workflows

after() deferred work, OutboundEffect reuse, and providers to plug in.

What Ships Today

One inbound endpoint, nothing else: no GitHub, no Slack, no Discord. Adding another follows Adding A Different Webhook Provider.

The Stripe Webhook

The route at apps/web/app/api/webhooks/stripe/route.ts verifies the signature, then delegates to processWebhookEvent in packages/payments/src/stripe/webhook.ts.

Endpoint And Signature Verification

It reads the raw body, verifies the Stripe signature against STRIPE_WEBHOOK_SECRET, and rejects a missing signature with 400 before any handler runs:

const signature = req.headers.get("stripe-signature");

if (!signature) {
  log.warn("Stripe webhook missing signature header", {
    attributes: { endpoint: "/api/webhooks/stripe" },
  });
  return new Response("Missing stripe-signature header", { status: 400 });
}

processWebhookEvent calls stripe.webhooks.constructEvent. A bad signature throws StripeWebhookSignatureError, which the route maps to 400; everything else falls through to a 500 with a structured log.

Two-Layer Idempotency

Stripe re-delivers events until it gets a 2xx. The kit guards against double-processing at two levels.

The event claim is an atomic prisma.stripeWebhookEvent.create({ status: "processing" }). The unique constraint on eventId turns a duplicate delivery into a P2002 error, which claimEvent inspects to pick one of three outcomes:

The side-effect layer adds a second guard inside the handlers: claimEffect("email", "subscription_created:sub_xxx") records the dispatch in OutboundEffect before the email sends. If a different Stripe event later resolves to the same business action (plan changes, trial conversions), the second dispatch sees the existing claim and skips. The key is always semantic, never the Stripe eventId, so the dedupe stays meaningful even when Stripe sends the "right" event under a different id.

Stale Processing Recovery

If a worker crashes mid-handler (lambda timeout, OOM, deploy interrupting the invocation), the StripeWebhookEvent row stays at status: processing with no one to clear it. claimEvent has two reclaim branches before it returns in_progress:

1. Failed reclaim. A row at status: failed is re-claimable. Failed events get another shot every Stripe retry.
2. Stale reclaim. A row whose createdAt is older than 5 minutes (STALE_PROCESSING_WINDOW_MS) is assumed dead and re-claimed.

const STALE_PROCESSING_WINDOW_MS = 5 * 60 * 1000;

const staleBefore = new Date(reclaimedAt.getTime() - STALE_PROCESSING_WINDOW_MS);

const staleReclaim = await prisma.stripeWebhookEvent.updateMany({
  where: {
    eventId,
    status: "processing",
    createdAt: { lt: staleBefore },
  },
  data: { status: "processing", failureReason: null, createdAt: reclaimedAt },
});

Combined with Stripe's exponential retry schedule (immediate, then minutes, then hours, up to 3 days), a stuck event recovers on its own within a retry or two of the 5-minute window. No manual intervention.

How It Holds Up Under Serverless Failure Modes

The cases that bite naive webhook handlers, and what the kit does instead.

Best-Effort Side Effects

Email and analytics don't run inline: they go through sendBestEffortWebhookEmail and sendBestEffortAnalyticsEvent, which claim, dispatch, then release the claim on failure:

async function sendBestEffortWebhookEmail(input) {
  const emailClaimed = await claimEffect("email", input.effectKey);
  if (!emailClaimed) return;

  try {
    const success = await sendEmail({
      to: input.to,
      subject: input.subject,
      body: input.body,
    });
    if (!success) throw new Error("Email provider reported unsuccessful delivery");
  } catch (error) {
    await releaseEffectClaim("email", input.effectKey);
    log.warn("Stripe webhook email delivery failed", {
      attributes: { effectKey: input.effectKey, error: String(error) },
    });
  }
}

• An email or analytics outage never fails the webhook. A 5xx from Plunk becomes a log.warn and a released OutboundEffect claim; the next Stripe retry attempts the email again.
• The dedupe survives retries. A successful dispatch keeps its claim, so a later retry that picks up where the first left off fires the email only once.

Events Handled Today

Nine event types, mapped to the business outcomes documented on the Billing page.

Adding A Stripe Event

export const subscriptionEventHandlers: Record<
  string,
  (event: Stripe.Event) => Promise<void>
> = {
  // ...
  "customer.subscription.paused": (event) =>
    handleSubscriptionPaused(
      ensurePayload<Stripe.Subscription>(event, "subscription")
    ),
};

Adding A Different Webhook Provider

Async Workflows

SyntaxKit ships zero scheduled jobs and zero background queues. The only code that runs outside a request is after()-deferred work in route handlers, plus the reusable OutboundEffect dedupe pattern. Buyers who need cron, durable execution, or long-running tasks bring their own provider. The kit doesn't pick a winner.

Vercel Cron

HTTP-triggered scheduled jobs, free on Vercel deployments. Easiest path if you're already on Vercel and need simple periodic work.

Inngest

Durable execution and step functions with at-least-once retries. Drop-in for multi-step workflows that need to survive crashes.

Trigger.dev

Alternative durable execution provider with a TypeScript-first SDK and deep Vercel and AWS integration.

Upstash QStash

HTTP-based scheduled and delayed delivery. Works with any HTTP endpoint, no agents to run. Same vendor as the Upstash Redis the kit already uses for abuse limits.

For non-application infra jobs, the kit already uses GitHub Actions cron for low-frequency CI work (.github/workflows/stripe-live.yml runs the live-billing suite at 03:00 UTC daily), the cheapest option you'll find.

return new Response("OK", { status: 200 });

after(async () => {
  await loggerProvider?.forceFlush();
});

// packages/payments/src/server.ts
export { claimEffect, releaseEffectClaim } from "./stripe/webhook/idempotency";

import { claimEffect, releaseEffectClaim } from "@syntaxkit/payments/server";

// In your scheduled job:
const claimed = await claimEffect("daily_digest", `digest:${userId}:${date}`);
if (!claimed) return;
try {
  await sendDailyDigest(userId);
} catch (error) {
  await releaseEffectClaim("daily_digest", `digest:${userId}:${date}`);
  throw error;
}

Where To Go Next