Webhooks act as real-time messengers between Uscreen and another platform. When events like sign-ups, purchases, or video plays occur, they automatically send data to your chosen systems. These digital notifications trigger actions without manual effort, enabling seamless workflows, data sync across platforms, and custom integrations that extend Uscreenβs functionality to fit your business needs.
π NOTE: The Webhooks feature is available for the App Essentials or Plus plan. If you're not currently on these plans, please get in touch with sales@uscreen.tv.
Set Up your Webhooks
Navigate to Settings > Webhooks
Click New Webhook
Enter the Callback URL and select an Event Type
Click Save
π NOTE: Webhooks are an advanced feature that requires technical expertise in APIs and external data management.
While our Support team can provide guidance in configuring webhooks and support Uscreen-related issues (such as webhook triggers not firing), we are unable to assist with custom configurations or third-party integrations.
If you are not familiar with webhooks, we recommend working with a qualified developer or technical expert.
Webhooks by Zapier
You can extend Zapierβs functionality by using Uscreen's webhooks as triggers. Search for Webhooks by Zapier to generate a Custom Webhook URL (Callback URL).
π‘ TIP: Be sure to double-check the Callback URL that you enter to ensure proper connection.
Event Types & Payloads
Subscription Assigned
Triggers when a user completes a checkout for a subscription or an admin manually grants subscription access.
{
"user_id": subscription.user.id,
"user_name": subscription.user.name,
"user_email": subscription.user.email,
"subscription_id": subscription.offer.id,
"subscription_title": subscription.offer.title,
"transaction_id": last_paid_invoice&.payment_id,
"event": "subscription_assigned"
}Compatibility: β Web | β Admin | β Apps | β API
βΉοΈ INFO: Transaction ID will be 'nil' for plans with a trial period
Use the Assigned Offer event for Content and Bundles access.
User Created
Triggers when a new user is created.
{
"id": user.id,
"name": user.name,
"email": user.email,
"custom_fields": { user.custom_fields.to_h },
"origin": user.creation_source,
"event": "user_created"
}Compatibility: β Web | β Admin | β Apps | β API
User Updated
Triggers when user information is updated, including admin edits, API changes, or mobile app updates.
{
"id": user.id,
"email": user.email,
"changes": {
"name": user.name,
"email": user.email,
"subscription_status": user.subscription_status,
"lifetime_spent": Money.new(user.lifetime_spent),
"bounced_email": user.bounced_email,
"status": user.status,
"field_1": user.field_1,
"field_2": user.field_2,
"field_3": user.field_3
},
"attributes": {
"name": user.name,
"email": user.email,
"subscription_status": user.subscription_status,
"lifetime_spent": user.lifetime_spent,
"bounced_email": user.bounced_email,
"segments": [user.segments,...],
"status": user.status,
"origin": user.creation_source
},
"event": "user_updated"
}Compatibility: β Web | β Admin | β Apps | β API
βΉοΈ INFO: The 'changes' field includes only the modified data, while the 'attributes' field contains all of the user data.
This event also fires when an admin deletes a user account.
Order Paid
Triggers when an invoice is marked as Paid.
{
"id": invoice.id,
"title": ownership.offer.title,
"total": Money.new(invoice.original_price, invoice.currency).to_s,
"amount": Money.new(invoice.final_price, invoice.currency).to_s,
"discount": Money.new(invoice.discount, invoice.currency).to_s,
"offer_id": ownership.product_id,
"customer_name": ownership.user.name,
"customer_email": ownership.user.email,
"country_code": purchase_location.country_code,
"transaction_id": invoice.payment_id,
"ip_address": ownership.purchase_ip,
"origin": order.provider_name,
"coupon": order.discount,
"event": "order_paid"
}Compatibility: β Web | β Admin | β Apps | β API
Access Canceled
Triggers when a subscription is canceled.
{
"id": ownership.id,
"name": ownership.user.name,
"email": ownership.user.email,
"offer_id": ownership.offer.id_param,
"offer_title": ownership.offer.title,
"ip_address": ownership.purchase_ip,
"origin": ownership.creation_source,
"currency": ownership.currency,
"transaction_id": last_paid_invoice&.payment_id,
"event": "subscription_canceled"
}Compatibility: β Web | β Admin | β Apps | β API
βΉοΈ INFO: Transaction ID will be 'nil' for plans with a trial period
Recurring Payment Successful
Triggers when a subscription is renewed.
β
{
"id": ownership.id,
"name": ownership.user.name,
"email": ownership.user.email,
"offer_id": ownership.offer.id_param,
"offer_title": ownership.offer.title,
"ip_address": ownership.purchase_ip,
"origin": ownership.creation_source,
"currency": ownership.currency,
"transaction_id": last_paid_invoice&.payment_id,
"event": "recurring_payment_successful"
}Compatibility: β Web | β Admin | β Apps | β API
βΉοΈ INFO: Transaction ID will be 'nil' for plans with a trial period
Began to Play Video
Triggers when a user starts watching a video.
{
"title": content.title,
"id": content.id,
"name": user.name,
"email": user.email,
"chapter_id": chapter.id,
"event": "video_play"
}Compatibility: β Web | β Admin | β Apps | β API
π NOTE: This event triggers only once per video per user and does not indicate whether the video was watched in full.
As of March 2025, this webhook is also supported on Android TV, Fire TV, and Samsung TV apps.
User Signed In
Triggers when a user logs into Uscreen.
β
{
"id": user.id,
"name": user.name,
"email": user.email,
"custom_fields": { user.custom_fields.to_h },
"origin": user.creation_source,
"event": "user_signed_in"
}Compatibility: β Web | β Admin | β Apps | β API
Added to Favorites
Triggers when a user adds content to their favorites.
β
{
"title": content.title,
"id": content.id,
"name": user.name,
"email": user.email,
"event": "added_to_favorites"
}Compatibility: β Web | β Admin | β Apps | β API
Invoice Overdue
Triggers when an invoice gets the Overdue status.
{
"invoice_id": invoice.id,
"user_id": invoice.user.id,
"name": user.try(:name),
"email": user.try(:email),
"title": invoice.product&.title,
"final_price": Money.new(invoice.final_price, invoice.currency).to_f,
"offer_id": invoice.ownership.offer&.id,
"transaction_id": invoice.payment_id,
"localized_amounts": {
"currency": invoice.localized_currency,
"amount": Money.new(invoice.localized_final_price, invoice.localized_currency).to_f
},
"event": "overdue_invoice"
}Compatibility: β Web | β Admin | β Apps | β API
βΉοΈ INFO: The 'name' and 'email' fields use 'try' method to handle 'nil' values safely.
Assigned Offer
Triggers when users gain access to content, bundles, or subscriptions.
{
"id": ownership.id,
"name": ownership.user.name,
"email": ownership.user.email,
"offer_id": ownership.offer.id_param,
"offer_title": ownership.offer.title,
"ip_address": ownership.purchase_ip,
"origin": ownership.creation_source,
"currency": ownership.currency,
"transaction_id": last_paid_invoice&.payment_id,
"event_date": Time.zone.today,
"event": "ownership_created"
}Compatibility: β Web | β Admin | β Apps | β API
Payment Method Updated
Triggers when a user updates their payment method.
{
"id": user.id,
"name": user.name,
"email": user.email,
"custom_fields": { user.custom_fields.to_h },
"origin": user.creation_source,
"event": "payment_method_updated"
}Compatibility: β Web | β Admin | β Apps | β API
Field Values Reference
Origin Values
Possible values for the origin field:
web_sign_up
admin_invite
migration
api
zapier
app_sign_up - User signed up via mobile/TV app
external - User created via external payment flow
purchased_by_user - User made a purchase
Segment Values
Possible values for the segment field (can be multiple):
one_time_buyer - User who purchased content or bundle once
in_trial - User currently in trial period
active - User with active subscription
churned - User who canceled or lost access
paused - User with paused subscription
email_capture - User who only provided email (no purchase)
lead - User who signed up but hasn't purchased
π NOTE: The Segment attribute can have multiple values, such as when a user has an Active subscription and also purchases a bundle or content (One Time Buyer)
Subscription Status Values [old]
Possible values for the subscription_status field:
never - Never had a subscription
in_trial - Currently in trial
active - Active subscription
pending_cancellation - Set to cancel
on_hold - On hold
former - Previously had subscription
pending_pausing - Set to pause
paused - Currently paused
βΉοΈ INFO: The Subscription Status is an old attribute of the JSON payload. It contains old values 'never', 'former', etc., that the platform is no longer using, but our Product team has decided to retain it for now, since there are other stores still using it
Status Values [new]
Possible values for the status field:
new - Newly created subscription/user
reactivated - Previously canceled subscription that was reactivated
upgraded - User upgraded their subscription
downgraded - User downgraded their subscription
on_hold - Subscription on hold (usually due to payment issues)
pending_cancellation - Subscription set to cancel at end of period
pending_pausing - Subscription set to pause
paused - Subscription currently paused
active - Active subscription (also appears in status field)
churned - Churned user (also appears in status field)
in_trial - User in trial (also appears in status field)
lead - Lead status (also appears in status field)
βΉοΈ INFO: The Status is the updated attribute that should align with the People page
Management and Best Practices
Response Handling
Your server must return a 200 HTTP status code within 5 seconds to acknowledge receipt
Any other response, including redirects (3xx), is considered a failure
Response body and headers are ignored
Retry System
If no valid response is received, the webhook will retry up to 3 times within a maximum interval of 15 minutes
If all retries fail, admin users will receive an email notification about the failure
Processing Time
Webhooks are in a lower-priority queue and may sometimes experience up to a 10-minute delay, depending on system availability.
Duplicate Events
Webhooks are not guaranteed to be delivered exactly once. This is standard behavior in most webhook-based systems, including Uscreen.
Even if your server is configured to respond correctly, network latency or processing delays can cause retries, resulting in duplicate webhook calls.
π‘ TIP: Implement idempotency logic on the receiving end to detect and handle duplicate webhook events.
Rate Limits
Uscreen maintains system stability with the following rate limits:
General API rate limit: 100 requests per minute
Sessions endpoint: 10 calls per 5 minutes
Webhook processing: Up to 100 requests per minute
β οΈ WARNING: Exceeding these limits will return a 429 (Too Many Requests) error.
Deliverability & Reliability
While 100% delivery cannot be guaranteed, Uscreen includes built-in fail-safes:
If a webhook process crashes, events are queued locally and retried when connectivity is restored
Each webhook event is attempted up to 3 times to improve deliverability
π‘ TIP: Schedule a monthly data backfill to ensure that you capture any missing webhook data.
Common Use Cases
Webhooks enable a wide range of workflows to elevate your Uscreen experience:
Marketing Automation
Add new users to your email marketing platform
Trigger personalized email sequences when users watch specific videos
External Invoicing
Connect with 3rd-party shop platforms like Shopify, WooCommerce, etc.
Forward user data to external invoice systems
Analytics & Reporting
Send viewing data to external analytics platforms
Track user engagement across multiple platforms
Customer Support
Trigger support tickets based on user behavior patterns
Sync customer information with your help desk software


