Guides · Free check · $9 fix pack

Guides

Stripe payment succeeded but the webhook can't find the user (metadata is empty)

The charge shows as paid in Stripe, your webhook returns 200 or a 500, and nobody gets unlocked. The log says user_id is undefined. Very often the code put the user's ID in the Checkout Session's metadata and then read it from a different object. Stripe: "An object's metadata doesn't automatically copy to related objects" (Stripe docs: Metadata).

Why metadata goes missing

Fix 1 (simplest): fulfill on checkout.session.completed

Handle checkout.session.completed and read the IDs from the Session itself. Pass your user's ID as client_reference_id, which Stripe describes as a string that "can be used to reconcile the session with your internal systems" (Stripe API: The Checkout Session object), or in the Session's metadata. The same Session also gives you payment_intent ("The ID of the PaymentIntent for Checkout Sessions in payment mode") and subscription, so save those on the user's row for later events (source). This is also the event Stripe's fulfillment guide is built on (Stripe docs: Fulfill orders).

Fix 2: copy the ID onto the PaymentIntent or Subscription too

If other code needs the ID on the PaymentIntent or Subscription (refunds, renewals, disputes), pass it at creation. payment_intent_data is "A subset of parameters to be passed to PaymentIntent creation for Checkout Sessions in payment mode", and it includes payment_intent_data.metadata (Stripe API: payment_intent_data.metadata). For subscriptions, subscription_data is "A subset of parameters to be passed to subscription creation for Checkout Sessions in subscription mode", with subscription_data.metadata (Stripe API: subscription_data.metadata).

// Server: create the Checkout Session
const userId = String(user.id);                       // metadata values are strings
const session = await stripe.checkout.sessions.create({
  mode: "payment",                                    // or "subscription"
  line_items: [{ price: process.env.PRICE_ID, quantity: 1 }],
  client_reference_id: userId,                        // on the Session
  metadata: { user_id: userId },                      // on the Session
  payment_intent_data: { metadata: { user_id: userId } },  // payment mode: on the PaymentIntent
  // subscription_data: { metadata: { user_id: userId } }, // subscription mode: on the Subscription
  success_url: "https://example.com/thanks?session_id={CHECKOUT_SESSION_ID}",
});

// Webhook (after verifying the signature with the raw body)
if (event.type === "checkout.session.completed") {
  const s = event.data.object;
  const uid = s.client_reference_id ?? s.metadata?.user_id;
  if (!uid) {                                         // don't swallow it
    await recordUnmatchedPayment(event.id, s.id);     // your helper: table + alert
  } else if (s.payment_status !== "unpaid") {
    await grantAccessOnce(uid, s.id);                 // your helper: unique on session id
  }
}

Helper names are placeholders. Payment mode passes payment_intent_data; subscription mode passes subscription_data instead.

Don't let a missing ID fail quietly

If the handler finds no user and still returns 200, Stripe marks the delivery as a success and nothing ever retries. Record the event ID and Session ID somewhere you'll see, and alert yourself. A retry won't help here, because the event will still have no ID in it. You can also catch past misses with a daily check of paid Sessions against your database: reconcile missed webhook events.

Other metadata gotchas

Prompt for your AI builder

Customers pay but our Stripe webhook can't find which user paid. 1) When creating the Checkout Session on the server, set client_reference_id to the signed-in user's ID as a string, and also set metadata.user_id. In payment mode add payment_intent_data.metadata.user_id; in subscription mode add subscription_data.metadata.user_id. 2) Grant access from the verified checkout.session.completed webhook (plus checkout.session.async_payment_succeeded), reading client_reference_id first and metadata.user_id second, skipping sessions whose payment_status is unpaid, once per session ID. 3) Save the session's payment_intent, customer and subscription IDs on the user's row. 4) Compare IDs as strings. 5) If no user ID is found, store the event ID and session ID in an unmatched_payments table and log an error; never return success silently. 6) Do not change the signature verification.

Re-test

  1. Run one sandbox Checkout from your app (not stripe trigger) with card 4242 4242 4242 4242.
  2. In the Dashboard, open the event and confirm client_reference_id / metadata.user_id are on the Session (and on the PaymentIntent or Subscription if you added Fix 2).
  3. Confirm the delivery returned 2xx and that test user is unlocked. Then send an unsigned POST to the webhook URL: it should return 400 (why). Still stuck? Start from customer paid but no access.
Check yours in 10 seconds (free).

Paste your webhook URL. WebhookProof sends 3 harmless test requests and tells you whether Stripe can reach it and whether it rejects unsigned events. If it finds a problem, the $9 fix pack gives you the exact copy-paste fix for your stack (refundable for 14 days).

Run the free check

FAQ

Why is metadata empty in my Stripe payment_intent.succeeded webhook?

Metadata set on a Checkout Session does not copy to the PaymentIntent. Stripe says an object's metadata doesn't automatically copy to related objects. Read it from checkout.session.completed, or also set payment_intent_data.metadata when you create the session.

How do I pass a user ID to a Stripe subscription created by Checkout?

Set subscription_data.metadata when creating the Checkout Session in subscription mode, and set client_reference_id so checkout.session.completed tells you which user paid.

Should I use client_reference_id or metadata for the user ID?

Either works on the Checkout Session. client_reference_id is a single string meant to reconcile the session with your own system; metadata holds up to 50 string key-value pairs. Many apps set both.

Why does my user lookup fail even though metadata has the ID?

Stripe stores metadata keys and values as strings, so a numeric user ID comes back as a string. Convert before comparing.

Sources

More guides

Stripe webhook not working? Check these 7 things in order · A customer paid but didn't get access. What went wrong? · No signatures found matching the expected signature for payload · Stripe webhook failing with a 307 or 308 redirect

Last reviewed 2026-11-12. WebhookProof is an independent tool, not affiliated with Stripe, Inc.. Quotes are from the linked documentation.