Revenue

Webhooks, event by event

Payments arrive by webhook from the provider, never from the browser. This is exactly which events are read and what each one does.

Updated All docs as one Markdown file

Events read, per provider

ProviderEndpointEventsVerified with
Stripe/api/webhooks/stripe/<website-id>checkout.session.completed, checkout.session.async_payment_succeeded, invoice.paid (subscription invoices only), charge.refundedThe endpoint signing secret, per website
Polar/api/webhooks/polar/<website-id>order.paid, refund.created, refund.updatedStandard Webhooks signature; payload format Raw
Creem/api/webhooks/creem/<website-id>checkout.completed, subscription.paid, refund.createdCreem's signature header
Dodo Payments/api/webhooks/dodo/<website-id>payment.succeeded, refund.succeededStandard Webhooks signature

Any other event answers ok and is ignored, so subscribing an endpoint to everything is harmless. Every endpoint is per website, and the secret is pasted into that website's Connect payments step; an event that fails verification answers 401 and nothing is written.

Repeats, renewals and refunds

  • The same event twice writes the same row twice, which is one row: payments are keyed by the provider's own id, so retries are safe.
  • A subscription's first invoice can arrive both as a checkout and as an invoice; the shared id makes them one payment.
  • A renewal is recorded as a renewal, which the MRR figures treat differently from a first payment.
  • A refund is a negative row against the original payment and inherits its visit, so refunded revenue leaves the same source it arrived from. A second partial refund replaces the first rather than adding to it.

A payment before its visit

A webhook can arrive before the pageview that produced the sale, or carry an identity the website has not seen. The payment is held rather than dropped, matched when the identity catches up, and listed in the website's Connect payments step while it waits. The rematch_payments MCP tool does the same by hand and says, per payment, why it could or could not be matched.

One account, several websites

Stripe sends every event to every endpoint, so two websites on one Stripe account each receive each payment. A payment is placed by an ml_site_id key in its metadata if you set one, else by the website the visitor was seen on, else, for a renewal, by where that customer paid before; one that none of those place on a website is not recorded there. Dodo Payments places by product: list each website's product ids in its settings.