Stripe webhook integration

OOOC Fête Finder receives partner activation payments through Stripe Payment Links. The webhook integration processes checkout.session.completed events, verifies signatures, extracts custom fields, and enqueues activations in the admin panel.

Configuration

Environment variables

STRIPE_WEBHOOK_SECRET=whsec_...

# Optional: Payment link ID mapping for admin queue labels
STRIPE_PAYMENT_LINK_ID_SPOTLIGHT_STANDARD=plink_...
STRIPE_PAYMENT_LINK_ID_SPOTLIGHT_TAKEOVER=plink_...
STRIPE_PAYMENT_LINK_ID_PROMOTED=plink_...
STRIPE_PAYMENT_LINK_ID_ADDON_WHATSAPP=plink_...
STRIPE_PAYMENT_LINK_ID_ADDON_NEWSLETTER=plink_...

If STRIPE_WEBHOOK_SECRET is not set, the webhook endpoint returns HTTP 503 and logs a warning.

Get webhook secret

Create webhook endpoint

Go to Stripe Dashboard
Click Add endpoint
Enter your webhook URL: https://your-domain.com/api/webhooks/stripe
Select event: checkout.session.completed

Copy signing secret

After creating the endpoint, Stripe displays the signing secret starting with whsec_.Copy this value.

Configure environment

Add the webhook secret to your environment:

STRIPE_WEBHOOK_SECRET=whsec_...

Webhook endpoint

The webhook is handled by POST /api/webhooks/stripe (app/api/webhooks/stripe/route.ts:10-50):

Verify signature

Extract stripe-signature header and verify webhook authenticity using HMAC SHA256.

Parse payload

Parse JSON payload and extract event type and data.

Process event

If event type is checkout.session.completed, extract session details and enqueue activation.

Return response

Return HTTP 200 with {ok: true, handled: boolean, inserted: boolean}.

Response codes

200 OK: Webhook processed successfully
400 Bad Request: Invalid signature
500 Internal Server Error: Processing failed
503 Service Unavailable: Webhook not configured

Signature verification

Stripe signs webhooks using HMAC SHA256 with the webhook secret (features/partners/stripe-webhook.ts:51-75).

Signature format

The stripe-signature header contains:

t=1614556800,v1=signature1,v1=signature2

t: Unix timestamp of the event
v1: HMAC SHA256 signature(s)

Verification algorithm

Parse signature header

Extract timestamp and v1 signatures.

Check timestamp

Verify event is within 5 minutes (300 seconds) of current time to prevent replay attacks.

Compute expected signature

const signedPayload = `${timestamp}.${payload}`;
const expected = createHmac('sha256', secret)
  .update(signedPayload, 'utf8')
  .digest('hex');

Compare signatures

Use timing-safe comparison to check if any provided signature matches the expected signature.

Invalid signature: If signature verification fails, the webhook returns HTTP 400 and the event is not processed. Check that STRIPE_WEBHOOK_SECRET matches the value in Stripe Dashboard.

Session data extraction

The integration extracts data from the checkout.session.completed event (features/partners/stripe-webhook.ts:150-201):

Custom fields

Stripe custom fields are extracted with fallback key matching:

// Event name: tries "event_name", "eventname"
const eventName = extractCustomFieldValue(
  customFields,
  ['event_name', 'eventname']
);

// Event URL: tries "event_url", "event_link", "ticket_link", "eventurl"
const eventUrl = extractCustomFieldValue(
  customFields,
  ['event_url', 'event_link', 'ticket_link', 'eventurl']
);

Custom field extraction supports text, dropdown, and numeric field types. Field keys are case-insensitive.

Payment link ID mapping

The system maps payment link IDs to package keys for admin queue organization:

Payment Link Env Var	Package Key
`STRIPE_PAYMENT_LINK_ID_SPOTLIGHT_STANDARD`	`spotlight-standard`
`STRIPE_PAYMENT_LINK_ID_SPOTLIGHT_TAKEOVER`	`spotlight-takeover`
`STRIPE_PAYMENT_LINK_ID_PROMOTED`	`promoted-listing`
`STRIPE_PAYMENT_LINK_ID_ADDON_WHATSAPP`	`addon-whatsapp`
`STRIPE_PAYMENT_LINK_ID_ADDON_NEWSLETTER`	`addon-newsletter`

If payment link ID doesn’t match any configured mapping, packageKey is null and the admin must manually categorize the activation.

Extracted fields

The following fields are extracted from the session:

{
  packageKey: string | null,           // Mapped from payment link ID
  paymentLinkId: string | null,        // Payment link ID
  stripeSessionId: string | null,      // Checkout session ID
  customerEmail: string | null,        // Customer email
  customerName: string | null,         // Customer name
  eventName: string | null,            // From custom field or metadata
  eventUrl: string | null,             // From custom field or metadata
  amountTotalCents: number | null,     // Total amount in cents
  currency: string | null,             // Currency code (e.g., "eur")
  metadata: Record<string, unknown>,   // Session metadata
}

Database storage

The webhook handler enqueues activations in the partner_activations table via enqueueFromStripe (features/partners/stripe-webhook.ts:203-233):

await repository.enqueueFromStripe({
  sourceEventId: event.id,           // Stripe event ID (for idempotency)
  packageKey: details.packageKey,
  paymentLinkId: details.paymentLinkId,
  stripeSessionId: details.stripeSessionId,
  customerEmail: details.customerEmail,
  customerName: details.customerName,
  eventName: details.eventName,
  eventUrl: details.eventUrl,
  amountTotalCents: details.amountTotalCents,
  currency: details.currency,
  metadata: details.metadata,
  rawPayload: {
    type: 'checkout.session.completed',
    session,
  },
});

Idempotency

The sourceEventId (Stripe event ID) ensures idempotency. If the same event is received multiple times, only the first insert succeeds.

The database schema includes a unique constraint on source_event_id to prevent duplicate processing.

Admin panel workflow

After webhook processing:

Activation appears in Admin > Partners > Queue
Admin reviews customer details, event info, and package
Admin manually activates the event or requests more information
Activation is marked as complete or rejected

Error handling

The integration handles errors at multiple levels:

Webhook endpoint errors

Webhook not configured (503): STRIPE_WEBHOOK_SECRET is not set in environment.

Invalid signature (400): Signature verification failed. Check that webhook secret matches Stripe Dashboard.

Webhook processing failed (500): Database error or unexpected payload structure. Check server logs for details.

Payload validation

If the payload is missing required fields, the webhook returns {handled: false}:

Missing event type
Missing event ID
Missing or invalid session object

Database errors

If the database is not configured or insert fails, the webhook throws an error and returns HTTP 500. Stripe will retry the webhook.

Testing webhooks

Local testing with Stripe CLI

Install Stripe CLI

Download from stripe.com/docs/stripe-cli

stripe login

Forward webhooks to localhost

stripe listen --forward-to localhost:3000/api/webhooks/stripe

The CLI displays a webhook signing secret starting with whsec_. Use this for STRIPE_WEBHOOK_SECRET during local development.

Trigger test events

stripe trigger checkout.session.completed

Manual testing

Use Stripe Dashboard to send test webhooks:

Go to Stripe Dashboard > Webhooks
Select your webhook endpoint
Click Send test webhook
Choose checkout.session.completed
Optionally edit JSON payload
Click Send test webhook

Security considerations

Signature verification: Always verify webhook signature before processing
Timing-safe comparison: Use timingSafeEqual to prevent timing attacks
Timestamp validation: Reject events older than 5 minutes
HTTPS only: Never expose webhook endpoints over HTTP
Secret rotation: Rotate webhook secret if compromised

Event types

Currently, the integration only processes:

checkout.session.completed - Customer completed checkout

Other event types are acknowledged but not processed:

if (type !== 'checkout.session.completed') {
  return { handled: true, inserted: false };
}

To process additional event types (e.g., payment_intent.succeeded), extend the handleStripeWebhookPayload function in features/partners/stripe-webhook.ts:235-261.

Monitoring

Monitor webhook health in Stripe Dashboard:

Go to Developers > Webhooks
Click on your endpoint
View Recent events and Response codes
Check for failed deliveries

Stripe retries failed webhooks with exponential backoff for up to 3 days.

Get Started

Architecture

Admin Guide

Operations

Integrations

Security

Configuration

Environment variables

Get webhook secret

Webhook endpoint

Response codes

Signature verification

Signature format

Verification algorithm

Session data extraction

Custom fields

Payment link ID mapping

Extracted fields

Database storage

Idempotency

Admin panel workflow

Error handling

Webhook endpoint errors

Payload validation

Database errors

Testing webhooks

Local testing with Stripe CLI

Manual testing

Security considerations

Event types

Monitoring

Build docs developers (and LLMs) love

Get Started

Architecture

Admin Guide

Operations

Integrations

Security

Documentation Index

​Configuration

​Environment variables

​Get webhook secret

​Webhook endpoint

​Response codes

​Signature verification

​Signature format

​Verification algorithm

​Session data extraction

​Custom fields

​Payment link ID mapping

​Extracted fields

​Database storage

​Idempotency

​Admin panel workflow

​Error handling

​Webhook endpoint errors

​Payload validation

​Database errors

​Testing webhooks

​Local testing with Stripe CLI

​Manual testing

​Security considerations

​Event types

​Monitoring

Build docs developers (and LLMs) love

Configuration

Environment variables

Get webhook secret

Webhook endpoint

Response codes

Signature verification

Signature format

Verification algorithm

Session data extraction

Custom fields

Payment link ID mapping

Extracted fields

Database storage

Idempotency

Admin panel workflow

Error handling

Webhook endpoint errors

Payload validation

Database errors

Testing webhooks

Local testing with Stripe CLI

Manual testing

Security considerations

Event types

Monitoring