Webhooks

Handle incoming webhook events from external services

Overview

Webhook endpoints receive and process events from external services. These endpoints verify payload signatures to ensure authenticity and security.

Stripe webhook

Receive and process Stripe events such as payment confirmations, subscription updates, and other partner-related notifications.

Endpoint

Path: /api/webhooks/stripe

Method: POST

Headers:

stripe-signature · string · required

Webhook signature generated by Stripe for payload verification.

This header is automatically added by Stripe when sending webhook events.

Content-Type · string · required

Must be application/json

Request

cURL

curl -X POST https://your-domain.com/api/webhooks/stripe \
  -H "Content-Type: application/json" \
  -H "stripe-signature: t=1234567890,v1=signature_hash" \
  -d '{"type": "checkout.session.completed", "data": {...}}'

The request body should be the raw Stripe event payload as JSON.

Response

200 OK

{
  "ok": true,
  "handled": true,
  "inserted": true
}

ok · boolean · required

Indicates whether the webhook was processed successfully.

handled · boolean · required

Whether the event type was recognized and handled.

inserted · boolean · required

Whether data was inserted into the database as a result of processing.

Error responses

400 Bad Request

{
  "error": "Invalid signature"
}

Status codes

Code	Description
200	Webhook processed successfully
400	Invalid signature verification
500	Internal error processing webhook
503	STRIPE_WEBHOOK_SECRET not configured

Authentication

Signature verification

The Stripe webhook endpoint uses signature verification to ensure requests are authentic:

1. Stripe signs each webhook with your STRIPE_WEBHOOK_SECRET
2. The signature is sent in the stripe-signature header
3. The endpoint verifies the signature before processing the payload
4. Invalid signatures are rejected with a 400 Bad Request response

The endpoint returns a 503 Service Unavailable status if STRIPE_WEBHOOK_SECRET is not configured in environment variables.

Configuration

Environment variables

STRIPE_WEBHOOK_SECRET · string · required

Secret key provided by Stripe for webhook signature verification.

Find this in your Stripe Dashboard under Developers > Webhooks.

Setting up webhooks in Stripe

1. Go to your Stripe Dashboard
2. Navigate to Developers > Webhooks
3. Click “Add endpoint”
4. Enter your endpoint URL: https://your-domain.com/api/webhooks/stripe
5. Select the events you want to receive
6. Copy the signing secret and set it as STRIPE_WEBHOOK_SECRET

Implementation details

The webhook handler:

1. Retrieves the webhook secret from STRIPE_WEBHOOK_SECRET
2. Reads the raw request body and stripe-signature header
3. Verifies the signature using Stripe’s verification method
4. Processes the validated payload
5. Returns processing results

See implementation: app/api/webhooks/stripe/route.ts:10