Webhooks

All endpoints are prefixed with /v1.

---

Stripe Webhook

POST /v1/webhook/stripe

Authentication: None (verified via stripe-signature header against STRIPE_WEBHOOK_SECRET).

Receives Stripe events, verifies the signature, and routes to the appropriate handler.

Handled Events

Event	Action
checkout.session.completed	Updates the payment record to paid. Handles wallet deposits by crediting the user balance. Routes to the appropriate app extension handler (e.g., courses, bundles, subscriptions) based on payment metadata.
customer.subscription.created	Updates the user’s profile subscription status and records the subscription details.
customer.subscription.updated	Updates the user’s profile subscription status when plan changes or renewals occur.
customer.subscription.deleted	Cancels the subscription and updates the user’s profile status.
account.updated	Updates the Stripe Connect account status for the connected user.

Response

{ "received": true }

Caution

This endpoint must be publicly accessible. Stripe will retry failed deliveries with exponential backoff. Always return a 200 status promptly to avoid retries.

---

Payment Succeeded

POST /v1/webhook/payment-succeeded

Authentication: API key (X-API-Key header).

Routes payment confirmations to the correct app handler. Called internally after Stripe confirms a payment. The payment metadata contains the app_slug which determines which extension’s payment-succeeded action is invoked.

Flow

1. Validate the API key.
2. Look up the payment record.
3. Determine the target app from payment metadata.
4. Invoke the app’s payment-succeeded action handler.

---

Ad Impression

POST /v1/ads/{id}/impression

Authentication: None (public).

Records an ad view. Called client-side when an ad is displayed to a user.

Parameter	Location	Type	Required	Description
id	path	string	Yes	The ad ID (UUID)

Behavior

• Increments the ad’s impression count.
• Checks the ad’s budget against total spend.
• Auto-pauses the ad if impressions exceed the budget threshold.

Response

Returns 200 on success.

---

Reports

POST /v1/reports

Authentication: Required (Bearer token or API key).

Submit a content report for moderation review.

Request Body

Field	Type	Required	Description
reportable_id	string	Yes	UUID of the reported resource.
reportable_type	string	Yes	Type of resource. One of: post, user, product, comment.
reason	string	Yes	Reason for the report.
description	string	No	Additional details about the report.

Response

Returns 201 Created on success.

{
  "id": "uuid",
  "reportable_id": "uuid",
  "reportable_type": "post",
  "reason": "spam",
  "description": "This post contains spam links.",
  "created_at": "2026-03-30T12:00:00Z"
}