Webhooks

Webhooks are an advanced functionality that allows you to send data out of Uscreen when a particular event takes place.

For example, if a user makes a purchase you could send the purchase data somewhere else to send a custom email, or add the user to a list in another software.

NOTE: You can use them to extend the functionality of Zapier to trigger actions. Search "Webhooks by Zapier" to use a webhook as a trigger event.

Outside of using webhooks with Zapier, setting up webhooks may require the help of a developer or someone familiar with programming, which our Support scope does not cover. You may want to hire a web developer.

NOTE: To integrate Uscreen with Zapier or use Webhooks, you need to be part of the Growth or Uscreen Plus plan. If you would like to know more about our plans, visit our pricing page or contact our sales team at sales@uscreen.tv.

Set Up Webhooks

1. Navigate to the Settings tab and select Webhooks

2. Click New webhook

3. Fill in Callback URL and choose an Event Type

4. Click Save to save changes

Webhook Payloads

Subscription Assigned

It triggers the endpoint when end-users complete the checkout on the web application or OTT apps, and admins grant access via the Admin Area or the API.

NOTE: It only fires the webhook for subscriptions. You may want to use Assigned Offer to also track Content and Bundles.

Body:

{
  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:

User Created

It triggers the endpoint when a new user is created.

Body:

{
  id: user.id,
  name: user.name,
  email: user.email,
  custom_fields: user.custom_fields,
  event: 'user_created'
}

Compatibility:

User Updated

It triggers the endpoint when user information is updated from the web application, admin area, or via API.

NOTE: It also fires the webhook when the admins delete a user account.

Body:

{
  id: user.id,
  changes: {
    name: user.name,
    email: user.email,
    subscription_status: user.subscription_status,
    lifetime_spent: Money.new(user.lifetime_spent, user.store.currency).format,
    bounced_email: user.bounced_email
    },
  event: 'user_updated'
}

Compatibility:

Order Paid

It triggers the endpoint when an invoice is paid, including purchases with 100% discounts.

NOTE: This webhook is on a lower-priority queue and therefore, can be triggered with a 10-minute delay, depending on the availability of the system. Also, the Transaction ID will be null (empty) for plans with a trial period.

Body:

{
  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,
  event: 'order_paid'
}

Compatibility:

Access Cancelled

It triggers the endpoint when a subscription is cancelled. It does not trigger when a subscription or content access is deleted.

Body:

{
  id: subscription.id,
  name: subscription.user.name,
  email: subscription.user.email,
  offer_id: subscription.offer.id_param,
  offer_title: subscription.offer.title,
  transaction_id: invoice.payment_id,
  ip_address: subscription.purchase_ip,
  event: 'subscription_canceled'
}

Compatibility:

Recurring Payment Successful

It triggers the endpoint when a recurring payment is successful.

NOTE: It doesn't fire the webhook for a trial period.

Body:

{
  id: subscription.id,
  name: subscription.user.name,
  email: subscription.user.email,
  offer_id: subscription.offer.id_param,
  offer_title: subscription.offer.title,
  transaction_id: invoice.payment_id,
  ip_address: subscription.purchase_ip,
  event: 'success_recurring'
}

Compatibility:

Began to Play Video

Formerly described as Video Played, it triggers the endpoint when a users open the program page on the web application and start watching a video.

NOTE: It will only fire the webhook when a video is played for the first time, and the end-user has access to view that content. This does not mean that the video was played in its entirety, just that the video was started and viewed for some duration greater than zero seconds.

Body:

{
  title: video.title,
  id: video.id,
  name: user.name,
  email: user.email,
  chapter_id: chapter.id
  event: 'video_play'
}

NOTE: We have deprecated the Chapters feature. We don't recommend using this webhook temporarily.

When users play a video from a collection, the chapter_id will be a positive integer with the deprecated chapter.id. However, when the video is played standalone, the chapter.id will be the video.id, which works fine.

Compatibility:

User Signed In

It triggers the endpoint when users sign into the web application or native apps.

Body:

{
  id: user.id,
  name: user.name,
  email: user.email,
  custom_fields: user.custom_fields
  event: 'user_signed_in'
}

Compatibility:

Added to Favorites

It triggers the endpoint when users add content to favorites.

Body:

{
  id: content.id,
  title: content.title,
  collection_id: collection.id,
  name: user.name,
  email: user.email,
  event: 'added_to_favorites'
}

NOTE: The collection.id field will be removed if the video was not marked as a favorite inside a collection.

Compatibility:

Overdue Invoice

It triggers the endpoint when users' status changes to overdue after multiple attempts have been made to collect a payment, but it has not succeeded about 30 days from the original due date.

Body:

{
  invoice_id: invoice.id,
  user_id: ownership.user.id,
  name: ownership.user.name,
  email: ownership.user.email,
  title: invoice.product.title,
  final_price: Money.new(invoice.final_price, invoice.currency).to_f,
  offer_id: ownership.offer.id,
  transaction_id: invoice.payment_id,
  event: 'invoice_overdue'
}

Compatibility:

Assigned Offer

It triggers when end-users complete the checkout on the web application or OTT apps, and admins grant access via the Admin Area or the API.

NOTE: It triggers the endpoint for all types of access, such as Content (Videos, Collections, Live Events), Bundles (Freebie, Fixed Price, Rentals), and Subscriptions.

Body:

{
  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,
  transaction_id: last_paid_invoice&.payment_id }
  event: 'ownership_created'
}

NOTE: Transaction ID will be null (empty) for plans with a trial period.

Compatibility:

Payment Method Updated

It triggers the endpoint when end-users update their payment methods on the web application.

Body:

{
  id: user.id,
  changes: {
    name: user.name,
    email: user.email,
    subscription_status: user.subscription_status,
    lifetime_spent: Money.new(user.lifetime_spent, user.store.currency).format,
    bounced_email: user.bounced_email
    },
  event: 'user_updated'
}

Compatibility:

Additional Notes

Deprecated Webhooks

The following webhooks are deprecated for Uscreen versions 8.4.0 and higher:

• Watched Video

Sending a Response to Webhooks

To acknowledge that you received the webhook without any problem, your server should return a 200 HTTP status code. You need to respond to the Webhook within 5 seconds.

Any other information you return in the request headers or request body will be ignored. Any response code outside of 200, including 3xx codes, will indicate that you did not receive the webhook.

Duplicate Webhook Events

Failing to respond with the 200 HTTP status code within five seconds will retrigger the webhook. The system will fire the webhook up to three times (with a maximum interval of 15 minutes). Then it will send an email notification informing you that the webhook delivery failed, which means that you need to debug your webhook catcher.

In some circumstances, a webhook can be triggered several times for the same event, we recommend implementing a script that checks for duplicates.

Rate Limits

Our webhooks can process up to 100 requests per minute

Deliverability Guarantee

While we can't guarantee that all webhooks will be sent, please rest assured that we have implemented several features to achieve the highest standards of reliability for Cloud environments.

We can guarantee that if a webhook process crashes or receives a networking error while pushing a job, our systems can withstand transient outages or timeouts. It will enqueue jobs locally upon error and attempt to deliver those jobs once connectivity is restored.

We recommend scheduling a monthly task to backfill potential missing data.