Stripe Webhooks

Stripe's webhooks are how Botsi finds out about web purchases, renewals, and refunds. There is no API call you make to report a purchase. The event arrives from Stripe, Botsi verifies it against your signing secret, then reads the subscription, customer, and invoice behind it.

Installing the Botsi app from the Stripe App Marketplace sets this up. See Connect to Stripe for the credentials involved.

Events Botsi processes#

Enable all of these. If you configure the endpoint manually, or want to audit what reaches Botsi, this is the complete list.

Events	What they tell Botsi
`invoice.paid`, `invoice.payment_failed`	Purchases, renewals, and billing issues. `invoice.payment_succeeded` is accepted as an alias
`customer.subscription.created` / `updated` / `deleted` / `paused` / `resumed`	Trials, cancellations, and other lifecycle changes
`checkout.session.completed`	Checkout Session purchases
`payment_intent.succeeded`, `payment_intent.payment_failed`	One-time purchases
`charge.refunded`, `refund.created`	Refunds
`charge.dispute.created`	Disputes
`customer.created` / `updated` / `deleted`, `invoice.created` / `updated` / `deleted`	Housekeeping that keeps Profiles and invoices in sync

Enabling everything listed is the simplest and safest option. Subscribing selectively means Botsi's view of a subscription is only as current as the events you chose to send.

Unsigned events are rejected

The webhook signing secret is what proves an event came from your Stripe account. Botsi rejects events it cannot verify, so the connection does not function without it.

That is deliberate: an unverified webhook endpoint is one anybody can post fabricated purchases to.

A transaction with no identifier becomes anonymous, permanently

If a transaction does not carry the identifier you selected, no Profile is created. The event is treated as anonymous unless something later associates it with a Profile, such as server-side validation.

Anonymous transactions still appear in Analytics, but they are excluded from everything that depends on Profile data (LTV, Cohorts, and Conversion metrics), and they do not appear in the Event Feed at all.

Skipping Profile creation entirely is possible and not advisable, for the same reason.

Moving users from your app to a web checkout#

App-to-web checkout runs on this same connection: your app sends the user to your web page, they pay there, and the webhook reports the purchase back to Botsi. Setting app_user_id (use appUserId) on the Stripe Customer is what lets that purchase reattach to the Profile that was shown the Paywall in the app.

Apple restricts promoting external payment systems from inside an app to the United States. See Connect to Stripe before building this flow.