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,
"segments": [user.segments,...],
"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
Webhook Management & 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