Connect Dodo Payments

Dodo Payments sends successful payments and refunds to a webhook signed with its secret. Checkout metadata links each payment to a visit.

Set up the webhook

1. Copy the webhook URL

   In MetricRaven, open Settings → Integrations → Dodo Payments and copy the webhook URL.

2. Add a webhook in Dodo Payments

   In the Dodo Payments dashboard, open Developer → Webhooks → Add Webhook. Paste the URL and select payment.succeeded and refund.succeeded. For subscription goals, also select the subscription.* events (active, on_hold, cancelled, expired, failed, plan_changed, updated).

3. Paste the signing secret in MetricRaven

   Copy the webhook's signing secret (whsec_…), paste it into the Dodo Payments card and choose Connect Dodo Payments.

Pass the visitor ID at checkout

Dodo stores checkout session metadata on the payment, and subscription renewals carry the subscription's metadata. Use these keys:

1. Read the visitor ID in the browser

   The MetricRaven script exposes window.analytics.getVisitorId(). Read it when checkout starts and send it to your checkout code:

   script.js

   Copy

   1

   2

   3

   4

   // Read this in the visitor's browser when they start checkout.
   const visitorId = window.analytics?.getVisitorId() ?? null;
   // Send visitorId to your own checkout endpoint alongside its usual request data.
   // Use the authenticated user ID from your backend; do not trust a browser-supplied user ID.

2. Add it to the checkout

   Checkout Sessions API

   Copy

   1

   2

   3

   4

   5

   6

   7

   8

   9

   10

   11

   // Server: create a checkout session with the Dodo Payments SDK (dodopayments).
   const session = await dodo.checkoutSessions.create({
     product_cart: [{ product_id: "pdt_YOUR_PRODUCT_ID", quantity: 1 }],
     customer: user ? { email: user.email, name: user.name } : undefined,
     return_url: "https://example.com/success",
     metadata: {
       ...(visitorId ? { metricraven_visitor_id: visitorId } : {}),
       ...(user ? { metricraven_user_id: user.id } : {}),
     },
   });
   // Redirect the visitor to session.checkout_url

   For a static payment link, add metadata_metricraven_visitor_id:

   Payment link

   Copy

   1

   2

   3

   4

   5

   // Browser: payment links turn ?metadata_<key>= into payment metadata.
   const url = new URL("https://checkout.dodopayments.com/buy/pdt_YOUR_PRODUCT_ID");
   const visitorId = window.analytics?.getVisitorId();
   if (visitorId) url.searchParams.set("metadata_metricraven_visitor_id", visitorId);
   window.location.href = url.toString();

MetricRaven links each payment to a visit using the first of these that is available:

1. The metricraven_visitor_id passed through checkout.
2. The metricraven_user_id (or the provider's customer external ID), matched to a visitor you linked with the Identify API.
3. An earlier payment from the same provider customer, so renewals keep the original attribution.
4. The checkout email, matched to an email you sent to the Identify API.
5. The checkout email, matched to a browser that called payment({ email }) within an hour of the payment.