Skip to main content
POST
/
webhooks
/
stripe
# This is typically called by Stripe, not manually
curl -X POST "https://searchcompany-main.up.railway.app/webhooks/stripe" \
  -H "Content-Type: application/json" \
  -H "stripe-signature: t=1234567890,v1=abc123..." \
  -d '{
    "type": "checkout.session.completed",
    "data": {
      "object": {
        "id": "cs_test_abc123",
        "customer": "cus_xyz789",
        "customer_email": "user@example.com",
        "subscription": "sub_def456",
        "client_reference_id": "nike"
      }
    }
  }'

{
  "status": "success"
}
This endpoint receives webhook events from Stripe and updates the corresponding Clerk organization and user metadata to keep subscription status in sync.
No authentication required - This is a public webhook endpoint. This endpoint is called by Stripe, not by your application directly. You must configure this URL in your Stripe Dashboard under Developers → Webhooks.

​
Headers

​
stripe-signature
string
required
Stripe webhook signature for verifying the request authenticity

​
Request Body

The request body is a raw Stripe webhook event payload. The endpoint handles the following event types:

​
checkout.session.completed

Triggered when a customer completes a checkout session. Actions:
  • Links Stripe customer ID to Clerk organization via client_reference_id
  • Stores stripeCustomerId, stripeSubscriptionId, and subscriptionStatus in organization metadata
  • Updates user metadata for backwards compatibility
  • Clears subscription cache for immediate status update

​
customer.subscription.updated

Triggered when a subscription is updated (e.g., plan change, renewal). Actions:
  • Updates subscriptionStatus in Clerk user metadata
  • Sets status to "active" for active or trialing subscriptions
  • Sets status to "inactive" for other states

​
customer.subscription.deleted

Triggered when a subscription is cancelled or expires. Actions:
  • Updates subscriptionStatus to "cancelled" in Clerk user metadata

​
Response

​
status
string
"success" when the webhook was processed successfully
# This is typically called by Stripe, not manually
curl -X POST "https://searchcompany-main.up.railway.app/webhooks/stripe" \
  -H "Content-Type: application/json" \
  -H "stripe-signature: t=1234567890,v1=abc123..." \
  -d '{
    "type": "checkout.session.completed",
    "data": {
      "object": {
        "id": "cs_test_abc123",
        "customer": "cus_xyz789",
        "customer_email": "user@example.com",
        "subscription": "sub_def456",
        "client_reference_id": "nike"
      }
    }
  }'

{
  "status": "success"
}

​
Errors

StatusDescription
400Invalid payload or invalid Stripe signature

​
Stripe Dashboard Configuration

To configure this webhook in Stripe:
  1. Go to Stripe Dashboard → Developers → Webhooks
  2. Click “Add endpoint”
  3. Enter the endpoint URL: https://searchcompany-main.up.railway.app/webhooks/stripe
  4. Select events to listen for:
    • checkout.session.completed
    • customer.subscription.updated
    • customer.subscription.deleted
  5. Copy the signing secret and set it as STRIPE_WEBHOOK_SECRET environment variable

​
Environment Variables

VariableDescription
STRIPE_API_KEYStripe API secret key
STRIPE_WEBHOOK_SECRETWebhook signing secret from Stripe Dashboard
CLERK_SECRET_KEYClerk secret key for updating user/org metadata