Webhooks And Async Workflows

On This Page

What Ships TodayOne inbound Stripe endpoint. Nothing else is wired.The Stripe WebhookSignature check, two-layer idempotency, reclaim rules, and events handled.Adding A Stripe EventRegister a handler, wrap side effects, subscribe in Stripe.Adding A Different Webhook ProviderRoute, signature, idempotency, and logging for a new provider.Async Workflowsafter() deferred work, OutboundEffect reuse, and providers to plug in.

What Ships Today

One inbound endpoint. No GitHub, Slack, or Discord webhook. To add another, follow Adding A Different Webhook Provider.

If billing is off (isBillingEnabled() is false), the route returns 503 and does not process events.

The Stripe Webhook

The route verifies the signature, then calls 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. Other thrown errors become 500 with a structured log.

Two-Layer Idempotency

Idempotency means running the same delivery twice has the same effect as running it once. Stripe re-delivers until it gets a 2xx, so the kit guards 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. claimEvent inspects that and returns one of four outcomes:

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

Stale Processing Recovery

If a worker crashes mid-handler (timeout, OOM, deploy kill), the StripeWebhookEvent row can stay at status: processing with no one to finish it. Before returning in_progress, claimEvent tries two reclaim paths. Both increment reclaimCount and stop after 5 reclaims:

1. Failed reclaim. A row at status: failed with reclaimCount < 5 is re-claimable so Stripe retries can recover from transient errors.
2. Stale reclaim. A row still at processing whose createdAt is older than 5 minutes (STALE_PROCESSING_WINDOW_MS) is treated as dead and re-claimed, also only while under the cap.

const STALE_PROCESSING_WINDOW_MS = 5 * 60 * 1000;
const MAX_RECLAIM_COUNT = 5;

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

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

Combined with Stripe's retry schedule (immediate, then minutes, then hours, up to 3 days), a stuck event usually recovers after the 5-minute window. After five reclaims the row goes terminal (failed_terminal), the route returns 200, and Stripe stops retrying. That is the escape hatch for a recurring crash loop.

How It Holds Up Under Serverless Failure Modes

Best-Effort Side Effects

Email and analytics go through sendBestEffortWebhookEmail and sendBestEffortAnalyticsEvent. Both use withDedupedEffect: claim, dispatch, release the claim on failure (and optionally escalate).

await sendBestEffortWebhookEmail({
  effectKey: "subscription_created:sub_xxx",
  to: owner.email,
  subject,
  body: html,
  // mustSucceed: true  // only for payment_failed / payment_action_required
});

• Default (mustSucceed unset or false). Welcome, receipt, trial, and cancellation emails, plus analytics. A Plunk outage becomes a log.warn and a released claim. The webhook still returns 200. A successful send keeps its claim, so a later retry does not send twice.
• mustSucceed: true. Used for invoice.payment_failed and invoice.payment_action_required. Failure fails the webhook (500) so Stripe retries. Confirmed sends stamp sentAt so retries do not re-send. Claims left with sentAt = null past 10 minutes can be reclaimed.

Events Handled Today

Nine event types. Billing owns the subscription lifecycle; this page owns delivery and idempotency. See Billing: The Webhook Path for the product-facing dispatch table.

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 no scheduled jobs and no background queues. The only work that runs after a response is after()-deferred work in route handlers, plus the reusable OutboundEffect dedupe pattern. If you need cron, durable execution, or long-running tasks, bring a provider. The kit does not pick one.

Vercel CronHTTP-triggered scheduled jobs on Vercel. Simple periodic work if you already deploy there.InngestDurable execution and step functions with at-least-once retries for multi-step workflows.Trigger.devDurable execution with a TypeScript-first SDK and strong Vercel and AWS integration.Upstash QStashHTTP-based scheduled and delayed delivery. Same vendor as the Upstash Redis the kit uses for abuse limits.

CI is separate from app workflows. .github/workflows/stripe-live.yml runs the live billing suite on manual dispatch (and a lightweight price-drift check on push to main). That is not an in-app job queue.

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

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

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

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

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

Also useful: Monitoring, Email, and Security.