Webhooks And Async Workflows

SyntaxKit ships inbound webhooks for its billing providers: three routes, one each for Stripe, Polar, and Creem. Only the active provider (BILLING_PROVIDER) processes events. Each route is signature-verified, deduped at two levels (event id and semantic side-effect key) through one shared ledger, 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.

There is still no queue vendor (no Inngest, Trigger.dev, or QStash). The one shipped worker is the usage-report cron at /api/cron/usage-reports when a fork declares a Stripe meter; see Usage billing. 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.

The Polar webhook

Standard Webhooks verification, webhook-id dedup, and the event set.

The Creem webhook

HMAC signature verification, event-id dedup, and the event set.

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

Three billing webhook routes, nothing else: no GitHub webhook, no Slack, no Discord. Adding another follows Adding A Different Webhook Provider.

These routes are thin: they read the raw body and call processBillingWebhook(provider, { body, headers }) from @syntaxkit/payments/server. That facade rejects a provider that is not the deployment's active one with BillingProviderInactiveError (the route answers 503 so the sender keeps retrying while an operator is mid-switch, instead of losing the event with a 2xx), and otherwise dispatches to the provider's adapter. Signature and header failures throw BillingWebhookSignatureError / BillingWebhookRequestError, which the routes map to 400; anything else is a 500 with a structured log and the provider retries.

The Stripe Webhook

The route at apps/web/app/api/webhooks/stripe/route.ts delegates to processStripeWebhookEvent in packages/payments/src/stripe/webhook.ts through the processBillingWebhook("stripe", …) facade.

Endpoint And Signature Verification

The adapter reads the raw body, verifies the Stripe signature against STRIPE_WEBHOOK_SECRET, and rejects a missing signature before any ledger write:

const signature = request.headers.get("stripe-signature");
if (!signature) {
  throw new BillingWebhookRequestError("Missing stripe-signature header");
}

let event: Stripe.Event;
try {
  event = stripe.webhooks.constructEvent(request.body, signature, webhookSecret);
} catch (error) {
  throw new BillingWebhookSignatureError(
    error instanceof Error ? error.message : "Invalid Stripe signature"
  );
}

The route maps BillingWebhookRequestError to a 400 with a log.warn (a missing header is noise, not an incident) and BillingWebhookSignatureError to a 400 with a log.error; 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 (WEBHOOK_ATTEMPT_LEASE_MS in packages/payments/src/ledger/webhook-events.ts) is assumed dead and re-claimed.

export const WEBHOOK_ATTEMPT_LEASE_MS = 5 * 60 * 1000;

const staleBefore = new Date(reclaimedAt.getTime() - WEBHOOK_ATTEMPT_LEASE_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 failed send becomes a log.warn and a released OutboundEffect claim; the next provider 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.

The Polar Webhook

The route at apps/web/app/api/webhooks/polar/route.ts (/api/webhooks/polar) delegates to processPolarWebhookEvent in packages/payments/src/polar/webhook.ts through processBillingWebhook("polar", …). It writes to the same StripeWebhookEvent and OutboundEffect tables as the Stripe route, tagged provider = polar, so two-layer idempotency, stale processing recovery, and best-effort side effects apply unchanged.

Verification

Polar signs with Standard Webhooks: the webhook-id, webhook-timestamp, and webhook-signature headers, with a five-minute timestamp tolerance. verifyPolarWebhook uses the standardwebhooks library and tries both key encodings a Polar secret can have (Polar changed its encoding on 2026-09-08; older secrets sign with the UTF-8 bytes of the whole whsec_… string, newer ones with the base64-decoded remainder), so an installation keeps verifying across the rotation without knowing which generation its secret is. Missing headers throw BillingWebhookRequestError (400, Polar does not retry); a bad signature or a timestamp outside the window throws BillingWebhookSignatureError (400). Both happen before any ledger write, so an attacker probing the endpoint cannot fill the event table. The verified body is then parsed with the SDK's typed schemas for handled event types; a signed payload this SDK version cannot read fails the event (5xx, Polar retries) so operators see the deployment problem instead of a silent ack.

Dedup and ordering

The dedup key is the webhook-id header, stored in StripeWebhookEvent.eventId. It is stable across Polar's redeliveries of the same event and distinct for distinct events, unlike the resource id inside the payload. The ordering signal is the payload timestamp (the event time), written to stripeLastEventAt as the provider event time; Polar documents send order but not delivery order, and the recency guard in the canonical subscription write makes a late delivery harmless. Polar retries a failed delivery up to 10 times with exponential backoff and disables an endpoint after 10 consecutive failures, so after an outage check Settings -> Webhooks in the Polar dashboard and re-enable the endpoint, then run pnpm billing:reconcile to catch up.

Correlation

Before a handler runs, correlatePolarEvent checks that every identifier the signed payload asserts about the owning organization agrees: the stored Organization.polarCustomerId mapping, the persisted subscription row (which must be a polar row), metadata.organizationId, and the customer's external_id. Any disagreement marks the association invalid; the event is recorded as failed for support visibility and no handler can fall back to one of the conflicting identifiers.

Events handled today

The lifecycle-level view (which phase each event lands in, which emails the kit sends versus Polar) is on Billing: Lifecycle semantics.

Recovery without manual replay

Polar exposes no authenticated "retrieve event by id" API, so the support console's manual webhook replay is unavailable for polar events (getWebhookRetryEligibility answers provider_unsupported). The recovery path is Compare and Resync on the organization in the support console, which re-fetch the live subscription and write it through the same canonical upsert, or pnpm billing:reconcile for a sweep. See Support console.

The Creem Webhook

The route at apps/web/app/api/webhooks/creem/route.ts (/api/webhooks/creem) delegates to processCreemWebhookEvent in packages/payments/src/creem/webhook.ts through processBillingWebhook("creem", …). Like Polar, it writes to the shared StripeWebhookEvent and OutboundEffect tables, tagged provider = creem, so two-layer idempotency, stale processing recovery, and best-effort side effects apply unchanged.

Verification

Creem signs the raw body with HMAC-SHA256 and sends the result in the creem-signature header. verifyCreemWebhook checks it against CREEM_WEBHOOK_SECRET with the Creem SDK's timing-safe helper. A missing header or a body that is not JSON throws BillingWebhookRequestError (400); a bad signature throws BillingWebhookSignatureError (400). Both happen before any ledger write. A verified payload that the kit cannot project is recorded as a failed event, reported as billing drift (creem_payload_unparseable), and acknowledged, so it shows up in the support console instead of being retried forever.

Dedup, ordering, and correlation

The dedup key is the payload event id (evt_…), stored in StripeWebhookEvent.eventId. The ordering signal is the payload created_at, written as the provider event time, so the recency guard in the canonical subscription write makes a late delivery harmless. Before a handler runs, correlateCreemEvent checks that the stored Organization.creemCustomerId, the persisted subscription row (which must be a creem row), and the asserted metadata.organizationId agree; any disagreement records the event as failed with no handler run.

Events handled today

Recovery without manual replay

The Creem adapter does not support manual webhook replay (getWebhookRetryEligibility answers provider_unsupported for creem events). Recover with Compare and Resync on the organization in the support console, which re-fetch the live subscription and write it through the same canonical upsert, or pnpm billing:reconcile for a sweep. See Support console.

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 a weekly catalog price-drift check), 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 "./ledger/webhook-events";

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