Skip to main content

VidApp API webhooks reference

Support
  • Updated

VidApp can POST lifecycle events to your own HTTPS endpoint as they happen. This page covers how delivery works and, for each event, when it fires and what the body looks like. For registering webhooks, see api.vidapp.com/docs.

How delivery works

  • Register one endpoint per event type with PUT /webhooks/subscribe. Events are delivered as an HTTP POST with a JSON body.
  • Your endpoint must be https:// and must respond with HTTP 200 - any other status (including 201 or 204) counts as a failure.
  • Delivery is at-least-once: on failure we retry three times, 30 minutes apart, so your handler should be idempotent (the same event can arrive more than once).
  • All timestamps are unix timestamps in seconds.
  • Every body includes event_type, event_format (always "VidApp"), and app_id.

UserSignUp

Sent when a new user account is created, on any platform (web or in-app).

{
  "event_type": "UserSignUp",
  "event_format": "VidApp",
  "app_id": "YourAppId",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "platform": "Web",
  "created_ts": 1753164000,
  "marketing_opt_in": true
}

UserUpdate

Sent when a user updates their profile: name, email, or marketing preference. previous_email is only present when the email changed.

{
  "event_type": "UserUpdate",
  "event_format": "VidApp",
  "app_id": "YourAppId",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane.new@example.com",
  "previous_email": "jane@example.com",
  "marketing_opt_in": true
}

SubscriptionCreated

Sent when a new subscription starts - on web when the Stripe subscription is created (including trials), on mobile on the first purchase. indicative_price is in USD.

{
  "event_type": "SubscriptionCreated",
  "event_format": "VidApp",
  "app_id": "YourAppId",
  "product_name": "Monthly Membership",
  "product_id": "monthly",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "purchase_ts": 1753164000,
  "platform": "Web",
  "interval": "month",
  "indicative_price": 19.99,
  "is_trial": false
}

SubscriptionChanged

Sent when a subscriber moves to a different plan (upgrade or downgrade). Carries the old and new product details.

{
  "event_type": "SubscriptionChanged",
  "event_format": "VidApp",
  "app_id": "YourAppId",
  "old_product_name": "Monthly Membership",
  "old_product_id": "monthly",
  "old_interval": "month",
  "old_indicative_price": 19.99,
  "new_product_name": "Annual Membership",
  "new_product_id": "annual",
  "new_interval": "year",
  "new_indicative_price": 179.99,
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "platform": "Web"
}

PendingCancellation

Sent when a subscriber requests cancellation but keeps access until the end of the billing period. cancel_requested_ts is when they cancelled; cancel_ts is when access will end.

{
  "event_type": "PendingCancellation",
  "event_format": "VidApp",
  "app_id": "YourAppId",
  "product_name": "Monthly Membership",
  "product_id": "monthly",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "cancel_requested_ts": 1753164000,
  "cancel_ts": 1755842400,
  "platform": "Web",
  "interval": "month",
  "indicative_price": 19.99,
  "is_trial": false
}

SubscriptionCancelled

Sent when access actually ends - a cancellation takes effect or the subscription lapses without renewing. cancel_ts is the cancellation time when one was recorded, otherwise the expiry time.

{
  "event_type": "SubscriptionCancelled",
  "event_format": "VidApp",
  "app_id": "YourAppId",
  "product_name": "Monthly Membership",
  "product_id": "monthly",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "cancel_ts": 1753164000,
  "platform": "Web",
  "interval": "month",
  "indicative_price": 19.99
}

TrialConverted

Sent when a free trial converts to a paid subscription.

{
  "event_type": "TrialConverted",
  "event_format": "VidApp",
  "app_id": "YourAppId",
  "product_name": "Monthly Membership",
  "product_id": "monthly",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "conversion_ts": 1753164000,
  "platform": "Web",
  "interval": "month",
  "indicative_price": 19.99
}

Unsubscribing

Call DELETE /webhooks/unsubscribe with the event type to stop receiving it. Full endpoint details: api.vidapp.com/docs.

Related articles