API Integration - Events Monitoring and Hooks

API Integration - Events Monitoring and Hooks

About Pixellot

Pixellot offers automated sports production solutions that provide affordable alternatives to traditional video capture, production, and distribution systems for professional and semi-professional sports events. Founded in 2013, Pixellot’s AI technology solution streamlines production workflow by deploying an unmanned multicamera system in a fixed location, with additional angles as required, to cover the entire field, offering a stitched panoramic image. Advanced algorithms enable automatic coverage of the flow of play and generate highlights. Pixellot systems are deployed by broadcasters, production companies, clubs, federations, universities, high schools, sports portals, and coaching solution providers around the globe.

For more information visit: www.pixellot.tv


Legal Notice

This document contains proprietary and confidential material of Pixellot Ltd. Any unauthorized reproduction, use, or disclosure of this material, or any part thereof, is strictly prohibited. This document is solely for the use of Pixellot employees and authorized Pixellot customers.

The material furnished in this document is believed to be accurate and reliable. However, no responsibility is assumed by Pixellot Ltd. for the use of this document or any material included herein. Pixellot Ltd. reserves the right to make changes to this document or any material included herein at any time and without notice. 

For more information visit: www.pixellot.tv 

Copyright © 2024 Pixellot Ltd.

All Rights Reserved.


Pixellot API

Pixellot provides its partners with a dedicated Partner API for creating new entities, updating and retrieving them. In addition, a partner can subscribe to Pixellot webhooks to get notification about different significant occurrences.

The idea is that a partner can, for instance, ask for a list of events on startup. When the partner subscribes to the webhooks service, it will get notifications about every significant change (including creation and deletion) and will update its own database. This will omit the need to repeatedly ask for the full list of events to get new events and updates to existing events. The updates can, in this way, be done passively in a push method instead of pull.

 

RestAPI documentation

Explore Partner API through our official documentation. This resource provides essential information for integrating our services seamlessly into your applications. Find detailed API endpoints, request methods, authentication guides, and error handling instructions.

For more information, visit our REST API documentation at https://app.swaggerhub.com/apis/Pixellot/partner_api/

Available environments:

[Base URL] = api.pixellot.tv/v1 (PROD) - production workloads
[Base URL] = api.stage.pixellot.tv/v1 (STAGE) - tests and integration


Authorization

All API requests, except for login, require the “Authorization” header to be present. Authorization is based on the JWT method. JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties.

To obtain authorization data, use the POST /login endpoint - https://app.swaggerhub.com/apis/Pixellot/partner_api/1.28.18#/default/login

Typical authenticated request would be having the following look:

  1. curl https://api.stage.pixellot.tv/v1/venues -H "Authorization: eyJ0eX..."


Webhook Subscriptions 


1. Overview 


As Pixellot’s solution contains many components, getting notifications about significant occurrences is one of its key functionalities. 

The manner in which this can be achieved is with the Webhooks Subscription mechanism. 

In order to use this mechanism, you have to inform Pixellot of your endpoint, your tenant and the type of data to which you want to subscribe. 

In response, every time an occurrence happens to such data, Pixellot will POST data to your endpoint along with header “X-Pixellot-Signature” including a hash of the data. 



2. How to subscribe 


POST [Base-URL]/subscriptions 

With body in the following schema: 


  1. {     
  2.       messageType: string,
  3.       url: string,
  4.       tenant: string,
  5.       secret: string,
  6.       emails: string
  7. }


Where messageType is the subscription name - EventChanges, EventTimestamp, ClipNotification or TeamChange, url is the url to which Pixellot’s platform will post, emails is an email(s), divided by comma, where Pixellot will send notifications on misbehaving subscriptions, and secret is a string that If provided, will be used as the key to generate the HMAC hex digest value in the X-Pixellot-Signature header. This can be used to authenticate the message when received. 


e.g. 

  1. {
  2. "tenant": "tenantName",
  3. "messageType": "EventChanges",
  5. "secret": "some-secret",
  7. }


Webhook handlers from Pixellot’s side are designed to ignore broken URLs after reaching a significant number of retries.  

If you notice that webhook message are not being received within the reasonable amount of time, it is a good idea to verify if the url to send updates to is valid, and can accept incoming requests. Therefore, during the testing process of a new integration, you may want to clean the old testing data which will not needed be in the future.


3. How to verify a message

X-Pixellot-Signature header can be used to authenticate the message when received.

A sample JS code to verify message content:

  1. const crypto = require('crypto');
  2.   
  3. const originalSecret = 'secret';
  4. const receivedMessage = 'Hook data';
  5. const expectedDigest = '...' // Replace this with the stored hexadecimal digest

  7. const computedDigest = crypto.createHmac('sha1', originalSecret).update(receivedMessage).digest('hex');

  9. if (computedDigest === expectedDigest) {
  10. console.log('Data is consistent.');
  11. } else {
  12. console.log('Data is not consistent.');
  13. }


4. How to update a subscription 


  1. PUT [Base-URL]/subscriptions/{id} 

Where {id} is the identifier of subscription you want to update 


5. How to unsubscribe 


  1. DELETE [Base-URL]/subscriptions/{id} 



Where {id} is the identifier of subscription you want to remove 


6. What do you get when you subscribe? 


There are several important to which you can subscribe: EventChanges, EventTimestamp, ClipNotification, and TeamChange.


 

6.1  EventTimestamp


When you subscribe to EventTimestamp, the data you’d receive would be of the following schema:


  1. {
  2.     eventId: string,
  3.     what: string,
  4.     when: Date,
  5.     event: {
  6.         name: string,
  7.         venueId: string,
  8.         status: string,
  9.         liveHdHlsUrl: string,
  10.         livePanoHlsUrl: string,
  11.         cloudRecordedHdMp4Url: string,
  12.         cloudRecordedPanoMp4Url: string,
  13.         cloudRecordedHdHlsUrl: string,
  14.         cloudRecordedPanoHlsUrl: string,
  15.         locallyRecordedHdMp4Url: string,
  16.         locallyRecordedPanoMp4Url: string,
  17.         locallyRecordedHdHlsUrl: string,
  18.         locallyRecordedPanoHlsUrl: string,
  19.         startDate: Date,
  20.         endDate: Date,
  21.         productionType: string,
  22.         location: string
  23.     }
  24. }


Where what is one of the following values:
  1. scheduled
  2. eventInitStarted
  3. liveHdUrlReady
  4. livePanoUrlReady
  5. eventEndReached
  6. cloudRecordedHdUrlReady
  7. cloudRecordedPanoUrlReady
  8. locallyRecordedHdUrlReady
  9. locallyRecordedPanoUrlReady
These messages will be sent when each of the above occurrences happen (what).

The order of messages per each event stage can differ. For example, you may receive “liveHdUrlReady” message 1 minute after “livePanoUrlReady” - this is normal, and should be handled by the integration client accordingly.


6.2  EventChanges

      
Event changes is most important for users who doesn’t manage their events scheduling, but also for any user, since it allows you to monitor your own changes, and verify they were applied.

When you subscribe to EventChanges the data you’d receive would be of the following schema:


  1. {
  2.     eventId: string,
  3.     name: string,
  4.     status: string,
  5.     startDate: string,
  6.     endDate: string,
  7.     productionType: string,
  8.     location: string,
  9.     labels: {
  10.       clubId: string,
  11.       tags: [string],
  12. teams: {
  13.   homeTeamId: string,
  14.   awayTeamId: string
  15. }
  16.     }
  17. }


Where status is one of the following values:
  1. active
    Corresponds to “upcoming” to “live” stages of the event.
  2. archiving
    Intermediate status before transitioning to “archived”.
  3. archived
    Event which has transitioned to the VOD state - either after being live, or after a manual upload. Event updates are still allowed for VOD.
  4. vodDeleted
    Event’s recordings have been removed from the stogare, as defined by tenant’s content lifecycle policy.
  5. deleted
    Similar to “vodDeleted”, but the event’s record is removed from CMS as well.

Please note that other parameters may be added to “labels” later on.

This message will be sent with only the changed data when the event is created, updated or deleted.


 

6.3  ClipNotification


When you subscribe to ClipNotification the data you’d receive would be of the following schema:

  1. {
  2.     eventId: string,
  3.     url: string,
  4.     when: Date,
  5.     clipType: string,
  6.     userId: string,
  7.     format: string
  8. }

Where clipType is one of the following values:
  1. userGeneratedHighlightFromClips
  2. userGeneratedHighlightFromTags
  3. userGeneratedClip
  4. adminTagBasedAutomaticHighlight
  5. adminUploadedHighlight
  6. automaticProductionHighlight
  7. playerHighlight
 

This message will be sent with the relevant data when a new clip or highlight is created.


Webhooks examples:

  1. {
  2.   "url": "https://d31o6fgd52u75b.cloudfront.net/Tenant/5ea556414a48ef1badad31cd/venue_hls/highlights_hls/highlights_hls.m3u8",
  3.   "eventId": "5ea556414a48ef1badad31cd",
  4.   "tenant": "Tenant",
  5.   "when": "2020-04-26T11:17:27.855Z",
  6.   "clipType": "automaticProductionHighlight",
  7.   "format": "hls",
  8.   "clipId": "b4a0e6f124dfgb497a942e9"
  9. }

Player highlights from a Basketball event using crowdsource:


  1. {
  2.   "url": "https://d31o6fgd52u75b.cloudfront.net/Tenant/events/5ea5514a48ef1badad31cd/player-highlights/5ea6b65ab44558b4dcf34e6b/a4921a3b9818fa4120f15ee82ce917fe.m3u8",
  3.   "eventId": "5ea55641c9ca8ef1adad37cd",
  4.   "tenant": "Tenant",
  5.   "when": "2020-04-27T09:31:06.554Z",
  6.   "clipType": "playerHighlight",
  7.   "clipDurationSeconds": 11,
  8.   "format": "hls",
  9.   "clipId": "5ea6b65ab44558b4dcf34e6b",
  10.   "playerNumber": "2",
  11.   "thumbnailUrl": "https://d2sz5b6nj0h5m0.cloudfront.net/demoTenant/events/5ea5514a48ef1badad31cd/player-highlights/5ea6b65ab44558b4dcf34e6b/scene0.png"
  12. }
 

6.4  TeamChange


When you subscribe to TeamChange, the data you’d receive would be of the following schema:

  1. {
  2.     teamId: string,
  3.     name: string,
  4.     shortName: string,
  5.     color: string,
  6.     tenant: string,
  7.     images: {
  8.         big: {
  9.             width: number,
  10.             height: number,
  11.             url: string
  12.           },
  13.       …
  14.     },
  15.     action: string
  16. }

Where action is one of the following values:
  1. created
  2. updated
This message will be sent with only the changed data when the team is created, or updated.

6.5  VasEventTimestamp

VasEventTimestamp subscription type can be used to get notifications on any VAS changes for event. For instance, when Pixellot notifies about the URL for Raw video content uploading.

When you subscribe to VasEventTimestamp, the data you’d receive would be of the following schema:
  1. {
        eventId: string,
        what: string,
        when: int64,
        vas: string
    }
Example payload:
  1. {
      "eventId": "6704c2c83d90dc69897057ef",
      "what": "created",
      "when": "2024-10-08T05:27:36.419Z",
      "vas": "PixellotVas",
      "event": {
        ...
        "vas": {
          "rawDataConsumer": {
            "name": "PixellotVas"
          }
        }
      },
      "venueId": "5b2278d25d5ad266e50b1cfe"
    }


Event Flow 

 

Event is scheduled in the Pixellot backend in advance 

EventTimestamp and EventChanges Webhooks are called with new event details  

15 min before event start – Pixellot starts automation process – setup cloud, waking up the venue, etc. 

EventTimestamp Webhook is called with eventInitStarted 

When event start time has passed and video streams are stable  

EventTimestamp Webhook is called with liveHdUrlReady and livePanoUrlReady to indicate live stream availability and provide urls 

At scheduled event end – Pixellot starts event archive process 

EventTimestamp Webhook is called with eventEndReached to indicate going off air 

1-5 min after scheduled event end – event archive process ends – VOD streams are available for consuming 

EventTimestamp Webhook is called with cloudRecordedHdUrlReady and cloudRecordedPanoUrlReady to indicate cloud recording availability and provide urls 

X minutes after the event end (X depends on event length) – Venue starts to upload local recording to Pixellot cloud 

No notification 

Y hours after event end (Y depends on event length, recorded bandwidth and venue bandwidth) – Venue finishes to upload to Pixellot cloud and best quality videos become available 

EventTimestamp Webhook is called with locallyRecordedHdUrlReady and locallyRecordedPanoUrlReady to indicate local recording availability and provide urls 

 

 


Convert to MP4


By default, the local recording in VOD is in HLS format only. To generate an MP4, you will need to call convertToMP4 API - POST [Base-URL]/events/:id/convert-to-mp4.

convertToMP4 is an API command that will generate an mp4 file from your hd/pano recording and send you the download link.

Running this command before local recording was uploaded will convert the cloud recording to mp4. Once local recording is fully uploaded (you can subscribe to EventTimestamp webhook, and get locallyRecordedHdUrlReady and locallyRecordedPanoUrlReady messages, as described earlier in this document), running the convert-to-mp4 will trigger a conversion for the local recording.

Conversion might take several minutes, depending the duration of the event.

Request schema:

  1. {
    "streamName": "hd",
    "email": "converted@mp4.com",
    "callback": {
        "url": "https://callback.com/mp4_result",
        "token": "<token>"
    }
}
  1. callbackUrl - optional
    1. url - is the url to which Pixellot’s platform will post. Required if using callbackUrl field
    2. token - authorization or labeling data to identify your request
  2. streamName is either "hd" or "pano"
  3. email is the destination address where the information about new MP4 will be sent.

Example of callback field value:
  1. {
  2.     "url": "https://webhook.site/15e32b5e-cb55-579d-a27a",
  3.     "token": "hd"
  4. }

Successful Response:

  1. 204 No Content
  2. []

Webhook sent:

  1. {
  2.   "status": "Ok",
  3.   "link": "https://test.cloudfront.net/example-tenant/events/5e6c6712c5028b794cbd15e4/streams/5e6c6712c5028b794cbd15e4_hd_local.mp4"
  4. }


Notes:
  1. Running conversion while event is Live will fail, since conversion is for VOD only
  2. Once mp4 file is generated, triggering another request will not re-generate the mp4, but only resend you the link to the existing mp4
  3. Running convert-to-mp4 while another convert-to-mp4 is already running will not trigger another conversion. When conversion is done, you will get one webhook notification
  4. There is an option to generate the MP4 through CMS. However, it is not recommended to use this feature if you are using API for that event.
 

    • Related Articles

    • API Integration - Events and Clubs

      About Pixellot Pixellot offers automated sports production solutions that provide affordable alternatives to traditional video capture, production, and distribution systems for professional and semi-professional sports events. Founded in 2013, ...

    • API Integration - Venue Monitoring

      About Pixellot Pixellot offers automated sports production solutions that provide affordable alternatives to traditional video capture, production, and distribution systems for professional and semi-professional sports events. Founded in 2013, ...

    • API Integration - Advanced Breakdown

      About Pixellot Pixellot offers automated sports production solutions that provide affordable alternatives to traditional video capture, production, and distribution systems for professional and semi-professional sports events. Founded in 2013, ...

    • API Integration - Onboarding and Best practices

      About Pixellot Pixellot offers automated sports production solutions that provide affordable alternatives to traditional video capture, production, and distribution systems for professional and semi-professional sports events. Founded in 2013, ...

    • API Integration - Pixellot Marketplace

      About Pixellot Pixellot offers automated sports production solutions that provide affordable alternatives to traditional video capture, production, and distribution systems for professional and semi-professional sports events. Founded in 2013, ...