Note: To integrate Uscreen with Zapier or use Webhooks, you must be on the App Essentials or Plus plan. If you would like to learn more about our plans, please visit our pricing page or contact our sales team at sales@uscreen.tv.
What Are Webhooks?
Webhooks allow you to send data from Uscreen to another platform when specific events occur.
For example, if a user makes a purchase, you can send the purchase data to another system to:
✅ Send a custom email.
✅ Add the user to a list in another software.
🔹 Using Webhooks with Zapier: You can extend Zapier’s functionality by using webhooks as triggers. Search for “Webhooks by Zapier” to use a webhook as a trigger event.
🔹 Technical Requirements: Outside of Zapier, setting up webhooks may require a developer or someone familiar with programming, which falls outside Uscreen’s support scope. You may want to hire a web developer for assistance.
🔹 Processing Time: Webhooks are in a lower-priority queue and may be triggered with up to a 10-minute delay, depending on system availability.
📌 Important Note: Webhooks are an advanced feature that requires technical knowledge to set up and manage. We strongly recommend using them only if you are comfortable working with webhooks, APIs, and handling data externally.
Uscreen can only provide support for issues on our end (e.g., webhook triggers not firing). We cannot assist with troubleshooting, custom implementations, or third-party integrations. If you’re unfamiliar with webhooks, we recommend working with a developer or technical expert.
How to Set Up Webhooks
1. Go to Settings > Webhooks.
2. Click New Webhook.
3. Enter the Callback URL and select an Event Type.
4. Click Save.
Webhook Event Types & Payloads
Each webhook event sends specific data to the receiving platform. Below are the key webhook events, their payloads, and compatibility across platforms.
Subscription Assigned
Triggers when a user completes a checkout for a subscription or an admin grants access.
📌 Note: This webhook only fires for subscriptions. Use Assigned Offer to track Content and Bundles access.
Payload:
{
"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
User Created
Triggers when a new user is created.
Payload:
{
"id": user.id,
"name": user.name,
"email": user.email,
"custom_fields": {
"custom_fields": "user.custom_fields"
},
"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.
📌 Note: Also fires when an admin deletes a user account.
Payload:
{
"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)
},
"attributes": {
"name": user.name,
"email": user.email,
"subscription_status": user.subscription_status,
"lifetime_spent": user.lifetime_spent,
"bounced_email": user.bounced_email,
"segments": ["active", "one_time_buyer"],
"status": "new"
},
"event": "user_updated"
}Compatibility: ✅ Web | ✅ Admin | ❌ Not Apps | ✅ API
Order Paid
Triggers when an invoice is paid (including 100% discounted purchases).
📌 Note: The transaction ID will be null for trial-based plans.
Payload:
{
"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
Began to Play Video
Triggers when a user starts watching a video on the web or apps.
📌 Note: Fires only once per video per user. Does not confirm if the video was watched in full.
📢 NEW: As of March 2025, this webhook is now supported on Android TV, Fire TV, and Samsung TV apps.
Payload:
{
"title": video.title,
"id": video.id,
"name": user.name,
"email": user.email,
"chapter_id": chapter.id,
"event": "video_play"
}Compatibility: ✅ Web | ❌ Admin | ✅ Apps | ❌ API
Additional Webhooks
Access Cancelled – Fires when a subscription is canceled.
Recurring Payment Successful – Fires for successful subscription payments.
User Signed In – Fires when a user logs into Uscreen.
Added to Favorites – Fires when a user favorites content.
Overdue Invoice – Fires when an invoice becomes overdue after 30 days.
Assigned Offer – Fires when users gain access to content, bundles, or subscriptions.
Payment Method Updated – Fires when a user updates their payment method.
Webhook Management & Best Practices
✅ Sending a Response
Your server must return a 200 HTTP status code within 5 seconds to confirm receipt.
Any other response (including 3xx codes) will be considered a failure.
🔄 Duplicate Webhook Events
If your server does not return a 200 HTTP status code in 5 seconds, the webhook will retry up to 3 times within 15 minutes.
If all retries fail, admin users will receive an email notification about the failure.
📌 Important: Webhooks are not guaranteed to be delivered exactly once. This is a 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 a script to detect and prevent duplicate webhook processing.
Performance & Reliability
⚡ Rate Limits
Uscreen webhooks process up to 100 requests per minute.
🔒 Deliverability Guarantee
While webhook delivery cannot be 100% guaranteed, Uscreen has built-in reliability mechanisms to handle errors.
If a webhook process crashes, Uscreen queues jobs locally and retries when connectivity is restored.
💡 Tip: Schedule a monthly data backfill to ensure you capture any missing webhook data.
Deprecated Webhooks
🚫 Watched Video webhook is deprecated for Uscreen 8.4.0+.